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