Development

/branches/1.2/lib/widget/sfWidget.class.php

You must first sign up to be able to contribute.

root/branches/1.2/lib/widget/sfWidget.class.php

Revision 21875, 9.7 kB (checked in by fabien, 5 years ago)

[1.2, 1.3] fixed PHPDoc (closes #6279)

  • Property svn:mime-type set to text/x-php
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
Line 
1 <?php
2
3 /*
4  * This file is part of the symfony package.
5  * (c) Fabien Potencier <fabien.potencier@symfony-project.com>
6  *
7  * For the full copyright and license information, please view the LICENSE
8  * file that was distributed with this source code.
9  */
10
11 /**
12  * sfWidget is the base class for all widgets.
13  *
14  * @package    symfony
15  * @subpackage widget
16  * @author     Fabien Potencier <fabien.potencier@symfony-project.com>
17  * @version    SVN: $Id$
18  */
19 abstract class sfWidget
20 {
21   protected
22     $requiredOptions = array(),
23     $attributes      = array(),
24     $options         = array();
25
26   protected static
27     $xhtml   = true,
28     $charset = 'UTF-8';
29
30   /**
31    * Constructor.
32    *
33    * @param array $options     An array of options
34    * @param array $attributes  An array of default HTML attributes
35    *
36    * @throws InvalidArgumentException when a option is not supported
37    * @throws RuntimeException         when a required option is not given
38    */
39   public function __construct($options = array(), $attributes = array())
40   {
41     $this->configure($options, $attributes);
42
43     $currentOptionKeys = array_keys($this->options);
44     $optionKeys = array_keys($options);
45
46     // check option names
47     if ($diff = array_diff($optionKeys, array_merge($currentOptionKeys, $this->requiredOptions)))
48     {
49       throw new InvalidArgumentException(sprintf('%s does not support the following options: \'%s\'.', get_class($this), implode('\', \'', $diff)));
50     }
51
52     // check required options
53     if ($diff = array_diff($this->requiredOptions, array_merge($currentOptionKeys, $optionKeys)))
54     {
55       throw new RuntimeException(sprintf('%s requires the following options: \'%s\'.', get_class($this), implode('\', \'', $diff)));
56     }
57
58     $this->options = array_merge($this->options, $options);
59     $this->attributes = array_merge($this->attributes, $attributes);
60   }
61
62   /**
63    * Configures the current widget.
64    *
65    * This method allows each widget to add options or HTML attributes
66    * during widget creation.
67    *
68    * If some options and HTML attributes are given in the sfWidget constructor
69    * they will take precedence over the options and HTML attributes you configure
70    * in this method.
71    *
72    * @param array $options     An array of options
73    * @param array $attributes  An array of HTML attributes
74    *
75    * @see __construct()
76    */
77   protected function configure($options = array(), $attributes = array())
78   {
79   }
80
81   /**
82    * Renders the widget as HTML.
83    *
84    * All subclasses must implement this method.
85    *
86    * @param  string $name       The name of the HTML widget
87    * @param  mixed  $value      The value of the widget
88    * @param  array  $attributes An array of HTML attributes
89    * @param  array  $errors     An array of errors
90    *
91    * @return string A HTML representation of the widget
92    */
93   abstract public function render($name, $value = null, $attributes = array(), $errors = array());
94
95   /**
96    * Adds a required option.
97    *
98    * @param string $name  The option name
99    */
100   public function addRequiredOption($name)
101   {
102     $this->requiredOptions[] = $name;
103   }
104
105   /**
106    * Returns all required option names.
107    *
108    * @return array An array of required option names
109    */
110   public function getRequiredOptions()
111   {
112     return $this->requiredOptions;
113   }
114
115   /**
116    * Adds a new option value with a default value.
117    *
118    * @param string $name   The option name
119    * @param mixed  $value  The default value
120    */
121   public function addOption($name, $value = null)
122   {
123     $this->options[$name] = $value;
124   }
125
126   /**
127    * Changes an option value.
128    *
129    * @param string $name   The option name
130    * @param mixed  $value  The value
131    *
132    * @throws InvalidArgumentException when a option is not supported
133    */
134   public function setOption($name, $value)
135   {
136     if (!in_array($name, array_merge(array_keys($this->options), $this->requiredOptions)))
137     {
138       throw new InvalidArgumentException(sprintf('%s does not support the following option: \'%s\'.', get_class($this), $name));
139     }
140
141     $this->options[$name] = $value;
142   }
143
144   /**
145    * Gets an option value.
146    *
147    * @param  string $name The option name
148    *
149    * @return mixed  The option value
150    */
151   public function getOption($name)
152   {
153     return isset($this->options[$name]) ? $this->options[$name] : null;
154   }
155
156   /**
157    * Returns true if the option exists.
158    *
159    * @param  string $name  The option name
160    *
161    * @return bool true if the option exists, false otherwise
162    */
163   public function hasOption($name)
164   {
165     return array_key_exists($name, $this->options);
166   }
167
168   /**
169    * Gets all options.
170    *
171    * @return array  An array of named options
172    */
173   public function getOptions()
174   {
175     return $this->options;
176   }
177
178   /**
179    * Sets the options.
180    *
181    * @param array $options  An array of options
182    */
183   public function setOptions($options)
184   {
185     $this->options = $options;
186   }
187
188   /**
189    * Returns the default HTML attributes.
190    *
191    * @param array An array of HTML attributes
192    */
193   public function getAttributes()
194   {
195     return $this->attributes;
196   }
197
198   /**
199    * Sets a default HTML attribute.
200    *
201    * @param string $name   The attribute name
202    * @param string $value  The attribute value
203    */
204   public function setAttribute($name, $value)
205   {
206     $this->attributes[$name] = $value;
207   }
208
209   /**
210    * Returns the HTML attribute value for a given attribute name.
211    *
212    * @param  string $name  The attribute name.
213    *
214    * @return string The attribute value, or null if the attribute does not exist
215    */
216   public function getAttribute($name)
217   {
218     return isset($this->attributes[$name]) ? $this->attributes[$name] : null;
219   }
220
221   /**
222    * Sets the HTML attributes.
223    *
224    * @param array $attributes  An array of HTML attributes
225    */
226   public function setAttributes($attributes)
227   {
228     $this->attributes = $attributes;
229   }
230
231   /**
232    * Gets the stylesheet paths associated with the widget.
233    *
234    * The array keys are files and values are the media names (separated by a ,):
235    *
236    *   array('/path/to/file.css' => 'all', '/another/file.css' => 'screen,print')
237    *
238    * @return array An array of stylesheet paths
239    */
240   public function getStylesheets()
241   {
242     return array();
243   }
244
245   /**
246    * Gets the JavaScript paths associated with the widget.
247    *
248    * @return array An array of JavaScript paths
249    */
250   public function getJavaScripts()
251   {
252     return array();
253   }
254
255   /**
256    * Sets the charset to use when rendering widgets.
257    *
258    * @param string $charset  The charset
259    */
260   static public function setCharset($charset)
261   {
262     self::$charset = $charset;
263   }
264
265   /**
266    * Returns the charset to use when rendering widgets.
267    *
268    * @return string The charset (defaults to UTF-8)
269    */
270   static public function getCharset()
271   {
272     return self::$charset;
273   }
274
275   /**
276    * Sets the XHTML generation flag.
277    *
278    * @param bool $boolean  true if widgets must be generated as XHTML, false otherwise
279    */
280   static public function setXhtml($boolean)
281   {
282     self::$xhtml = (boolean) $boolean;
283   }
284
285   /**
286    * Returns whether to generate XHTML tags or not.
287    *
288    * @return bool true if widgets must be generated as XHTML, false otherwise
289    */
290   static public function isXhtml()
291   {
292     return self::$xhtml;
293   }
294
295   /**
296    * Renders a HTML tag.
297    *
298    * @param string $tag         The tag name
299    * @param array  $attributes  An array of HTML attributes to be merged with the default HTML attributes
300    *
301    * @param string An HTML tag string
302    */
303   public function renderTag($tag, $attributes = array())
304   {
305     if (empty($tag))
306     {
307       return '';
308     }
309
310     return sprintf('<%s%s%s', $tag, $this->attributesToHtml($attributes), self::$xhtml ? ' />' : (strtolower($tag) == 'input' ? '>' : sprintf('></%s>', $tag)));
311   }
312
313   /**
314    * Renders a HTML content tag.
315    *
316    * @param string $tag         The tag name
317    * @param string $content     The content of the tag
318    * @param array  $attributes  An array of HTML attributes to be merged with the default HTML attributes
319    *
320    * @param string An HTML tag string
321    */
322   public function renderContentTag($tag, $content = null, $attributes = array())
323   {
324     if (empty($tag))
325     {
326       return '';
327     }
328
329     return sprintf('<%s%s>%s</%s>', $tag, $this->attributesToHtml($attributes), $content, $tag);
330   }
331
332   /**
333    * Escapes a string.
334    *
335    * @param  string $value  string to escape
336    * @return string escaped string
337    */
338   static public function escapeOnce($value)
339   {
340     $value = is_object($value) ? $value->__toString() : (string) $value;
341
342     return self::fixDoubleEscape(htmlspecialchars($value, ENT_QUOTES, self::getCharset()));
343   }
344
345   /**
346    * Fixes double escaped strings.
347    *
348    * @param  string $escaped  string to fix
349    * @return string single escaped string
350    */
351   static public function fixDoubleEscape($escaped)
352   {
353     return preg_replace('/&amp;([a-z]+|(#\d+)|(#x[\da-f]+));/i', '&$1;', $escaped);
354   }
355
356   /**
357    * Converts an array of attributes to its HTML representation.
358    *
359    * @param  array  $attributes An array of attributes
360    *
361    * @return string The HTML representation of the HTML attribute array.
362    */
363   public function attributesToHtml($attributes)
364   {
365     $attributes = array_merge($this->attributes, $attributes);
366
367     return implode('', array_map(array($this, 'attributesToHtmlCallback'), array_keys($attributes), array_values($attributes)));
368   }
369
370   /**
371    * Prepares an attribute key and value for HTML representation.
372    *
373    * It removes empty attributes, except for the value one.
374    *
375    * @param  string $k  The attribute key
376    * @param  string $v  The attribute value
377    *
378    * @return string The HTML representation of the HTML key attribute pair.
379    */
380   protected function attributesToHtmlCallback($k, $v)
381   {
382     return false === $v || is_null($v) || ('' === $v && 'value' != $k) ? '' : sprintf(' %s="%s"', $k, $this->escapeOnce($v));
383   }
384 }
385
Note: See TracBrowser for help on using the browser.