xref: /dokuwiki/inc/Form/Element.php (revision 12a4e4d1ed827c59290838d5a11d75ad32aa28f1) 
1*12a4e4d1SAndreas Gohr<?php
2*12a4e4d1SAndreas Gohrnamespace dokuwiki\Form;
3*12a4e4d1SAndreas Gohr
4*12a4e4d1SAndreas Gohr
5*12a4e4d1SAndreas Gohr/**
6*12a4e4d1SAndreas Gohr * Class Element
7*12a4e4d1SAndreas Gohr *
8*12a4e4d1SAndreas Gohr * The basic building block of a form
9*12a4e4d1SAndreas Gohr *
10*12a4e4d1SAndreas Gohr * @package dokuwiki\Form
11*12a4e4d1SAndreas Gohr */
12*12a4e4d1SAndreas Gohrabstract class Element {
13*12a4e4d1SAndreas Gohr
14*12a4e4d1SAndreas Gohr    /**
15*12a4e4d1SAndreas Gohr     * @var array the attributes of this element
16*12a4e4d1SAndreas Gohr     */
17*12a4e4d1SAndreas Gohr    protected $attributes = array();
18*12a4e4d1SAndreas Gohr
19*12a4e4d1SAndreas Gohr    /**
20*12a4e4d1SAndreas Gohr     * @var string The type of this element
21*12a4e4d1SAndreas Gohr     */
22*12a4e4d1SAndreas Gohr    protected $type;
23*12a4e4d1SAndreas Gohr
24*12a4e4d1SAndreas Gohr    /**
25*12a4e4d1SAndreas Gohr     * @param string $type The type of this element
26*12a4e4d1SAndreas Gohr     * @param array $attributes
27*12a4e4d1SAndreas Gohr     */
28*12a4e4d1SAndreas Gohr    public function __construct($type, $attributes = array()) {
29*12a4e4d1SAndreas Gohr        $this->type = $type;
30*12a4e4d1SAndreas Gohr        $this->attributes = $attributes;
31*12a4e4d1SAndreas Gohr    }
32*12a4e4d1SAndreas Gohr
33*12a4e4d1SAndreas Gohr    /**
34*12a4e4d1SAndreas Gohr     * Gets or sets an attribute
35*12a4e4d1SAndreas Gohr     *
36*12a4e4d1SAndreas Gohr     * When no $value is given, the current content of the attribute is returned.
37*12a4e4d1SAndreas Gohr     * An empty string is returned for unset attributes.
38*12a4e4d1SAndreas Gohr     *
39*12a4e4d1SAndreas Gohr     * When a $value is given, the content is set to that value and the Element
40*12a4e4d1SAndreas Gohr     * itself is returned for easy chaining
41*12a4e4d1SAndreas Gohr     *
42*12a4e4d1SAndreas Gohr     * @param string $name Name of the attribute to access
43*12a4e4d1SAndreas Gohr     * @param null|string $value New value to set
44*12a4e4d1SAndreas Gohr     * @return string|$this
45*12a4e4d1SAndreas Gohr     */
46*12a4e4d1SAndreas Gohr    public function attr($name, $value = null) {
47*12a4e4d1SAndreas Gohr        // set
48*12a4e4d1SAndreas Gohr        if($value !== null) {
49*12a4e4d1SAndreas Gohr            $this->attributes[$name] = $value;
50*12a4e4d1SAndreas Gohr            return $this;
51*12a4e4d1SAndreas Gohr        }
52*12a4e4d1SAndreas Gohr
53*12a4e4d1SAndreas Gohr        // get
54*12a4e4d1SAndreas Gohr        if(isset($this->attributes[$name])) {
55*12a4e4d1SAndreas Gohr            return $this->attributes[$name];
56*12a4e4d1SAndreas Gohr        } else {
57*12a4e4d1SAndreas Gohr            return '';
58*12a4e4d1SAndreas Gohr        }
59*12a4e4d1SAndreas Gohr    }
60*12a4e4d1SAndreas Gohr
61*12a4e4d1SAndreas Gohr    /**
62*12a4e4d1SAndreas Gohr     * Removes the given attribute if it exists
63*12a4e4d1SAndreas Gohr     *
64*12a4e4d1SAndreas Gohr     * @param $name
65*12a4e4d1SAndreas Gohr     * @return $this
66*12a4e4d1SAndreas Gohr     */
67*12a4e4d1SAndreas Gohr    public function rmattr($name) {
68*12a4e4d1SAndreas Gohr        if(isset($this->attributes[$name])) {
69*12a4e4d1SAndreas Gohr            unset($this->attributes[$name]);
70*12a4e4d1SAndreas Gohr        }
71*12a4e4d1SAndreas Gohr        return $this;
72*12a4e4d1SAndreas Gohr    }
73*12a4e4d1SAndreas Gohr
74*12a4e4d1SAndreas Gohr    /**
75*12a4e4d1SAndreas Gohr     * Gets or adds a all given attributes at once
76*12a4e4d1SAndreas Gohr     *
77*12a4e4d1SAndreas Gohr     * @param array|null $attributes
78*12a4e4d1SAndreas Gohr     * @return array|$this
79*12a4e4d1SAndreas Gohr     */
80*12a4e4d1SAndreas Gohr    public function attrs($attributes = null) {
81*12a4e4d1SAndreas Gohr        // set
82*12a4e4d1SAndreas Gohr        if($attributes) {
83*12a4e4d1SAndreas Gohr            foreach((array) $attributes as $key => $val) {
84*12a4e4d1SAndreas Gohr                $this->attr($key, $val);
85*12a4e4d1SAndreas Gohr            }
86*12a4e4d1SAndreas Gohr            return $this;
87*12a4e4d1SAndreas Gohr        }
88*12a4e4d1SAndreas Gohr        // get
89*12a4e4d1SAndreas Gohr        return $this->attributes;
90*12a4e4d1SAndreas Gohr    }
91*12a4e4d1SAndreas Gohr
92*12a4e4d1SAndreas Gohr    /**
93*12a4e4d1SAndreas Gohr     * Adds a class to the class attribute
94*12a4e4d1SAndreas Gohr     *
95*12a4e4d1SAndreas Gohr     * This is the preferred method of setting the element's class
96*12a4e4d1SAndreas Gohr     *
97*12a4e4d1SAndreas Gohr     * @param string $class the new class to add
98*12a4e4d1SAndreas Gohr     * @return $this
99*12a4e4d1SAndreas Gohr     */
100*12a4e4d1SAndreas Gohr    public function addClass($class) {
101*12a4e4d1SAndreas Gohr        $classes = explode(' ', $this->attr('class'));
102*12a4e4d1SAndreas Gohr        $classes[] = $class;
103*12a4e4d1SAndreas Gohr        $classes = array_unique($classes);
104*12a4e4d1SAndreas Gohr        $this->attr('class', join(' ', $classes));
105*12a4e4d1SAndreas Gohr        return $this;
106*12a4e4d1SAndreas Gohr    }
107*12a4e4d1SAndreas Gohr
108*12a4e4d1SAndreas Gohr    /**
109*12a4e4d1SAndreas Gohr     * Get or set the element's ID
110*12a4e4d1SAndreas Gohr     *
111*12a4e4d1SAndreas Gohr     * This is the preferred way of setting the element's ID
112*12a4e4d1SAndreas Gohr     *
113*12a4e4d1SAndreas Gohr     * @param null|string $id
114*12a4e4d1SAndreas Gohr     * @return string|$this
115*12a4e4d1SAndreas Gohr     */
116*12a4e4d1SAndreas Gohr    public function id($id = null) {
117*12a4e4d1SAndreas Gohr        if(strpos($id, '__') === false) {
118*12a4e4d1SAndreas Gohr            throw new \InvalidArgumentException('IDs in DokuWiki have to contain two subsequent underscores');
119*12a4e4d1SAndreas Gohr        }
120*12a4e4d1SAndreas Gohr
121*12a4e4d1SAndreas Gohr        return $this->attr('id', $id);
122*12a4e4d1SAndreas Gohr    }
123*12a4e4d1SAndreas Gohr
124*12a4e4d1SAndreas Gohr    /**
125*12a4e4d1SAndreas Gohr     * Get or set the element's value
126*12a4e4d1SAndreas Gohr     *
127*12a4e4d1SAndreas Gohr     * This is the preferred way of setting the element's value
128*12a4e4d1SAndreas Gohr     *
129*12a4e4d1SAndreas Gohr     * @param null|string $value
130*12a4e4d1SAndreas Gohr     * @return string|$this
131*12a4e4d1SAndreas Gohr     */
132*12a4e4d1SAndreas Gohr    public function val($value = null) {
133*12a4e4d1SAndreas Gohr        return $this->attr('value', $value);
134*12a4e4d1SAndreas Gohr    }
135*12a4e4d1SAndreas Gohr
136*12a4e4d1SAndreas Gohr    /**
137*12a4e4d1SAndreas Gohr     * The HTML representation of this element
138*12a4e4d1SAndreas Gohr     *
139*12a4e4d1SAndreas Gohr     * @return string
140*12a4e4d1SAndreas Gohr     */
141*12a4e4d1SAndreas Gohr    abstract public function toHTML();
142*12a4e4d1SAndreas Gohr}
143