www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Render/Element/HtmlTag.php

   1 <?php
   2
   3 namespace Drupal\Core\Render\Element;
   4
   5 use Drupal\Component\Render\MarkupInterface;
   6 use Drupal\Component\Utility\Html as HtmlUtility;
   7 use Drupal\Core\Render\Markup;
   8 use Drupal\Component\Utility\Xss;
   9 use Drupal\Core\Template\Attribute;
  10
  11 /**
  12  * Provides a render element for any HTML tag, with properties and value.
  13  *
  14  * Properties:
  15  * - #tag: The tag name to output.
  16  * - #attributes: (array, optional) HTML attributes to apply to the tag. The
  17  *   attributes are escaped, see \Drupal\Core\Template\Attribute.
  18  * - #value: (string, optional) A string containing the textual contents of
  19  *   the tag.
  20  * - #noscript: (bool, optional) When set to TRUE, the markup
  21  *   (including any prefix or suffix) will be wrapped in a <noscript> element.
  22  *
  23  * Usage example:
  24  * @code
  25  * $build['hello'] = [
  26  *   '#type' => 'html_tag',
  27  *   '#tag' => 'p',
  28  *   '#value' => $this->t('Hello World'),
  29  * ];
  30  * @endcode
  31  *
  32  * @RenderElement("html_tag")
  33  */
  34 class HtmlTag extends RenderElement {
  35
  36   /**
  37    * Void elements do not contain values or closing tags.
  38    * @see http://www.w3.org/TR/html5/syntax.html#syntax-start-tag
  39    * @see http://www.w3.org/TR/html5/syntax.html#void-elements
  40    */
  41   static protected $voidElements = [
  42     'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
  43     'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr',
  44     'rect', 'circle', 'polygon', 'ellipse', 'stop', 'use', 'path',
  45   ];
  46
  47   /**
  48    * {@inheritdoc}
  49    */
  50   public function getInfo() {
  51     $class = get_class($this);
  52     return [
  53       '#pre_render' => [
  54         [$class, 'preRenderConditionalComments'],
  55         [$class, 'preRenderHtmlTag'],
  56       ],
  57       '#attributes' => [],
  58       '#value' => NULL,
  59     ];
  60   }
  61
  62   /**
  63    * Pre-render callback: Renders a generic HTML tag with attributes.
  64    *
  65    * @param array $element
  66    *   An associative array containing:
  67    *   - #tag: The tag name to output. Typical tags added to the HTML HEAD:
  68    *     - meta: To provide meta information, such as a page refresh.
  69    *     - link: To refer to stylesheets and other contextual information.
  70    *     - script: To load JavaScript.
  71    *     The value of #tag is escaped.
  72    *   - #attributes: (optional) An array of HTML attributes to apply to the
  73    *     tag. The attributes are escaped, see \Drupal\Core\Template\Attribute.
  74    *   - #value: (optional) A string containing tag content, such as inline
  75    *     CSS. The value of #value will be XSS admin filtered if it is not safe.
  76    *   - #noscript: (optional) If TRUE, the markup (including any prefix or
  77    *     suffix) will be wrapped in a <noscript> element. (Note that passing
  78    *     any non-empty value here will add the <noscript> tag.)
  79    *
  80    * @return array
  81    */
  82   public static function preRenderHtmlTag($element) {
  83     $attributes = isset($element['#attributes']) ? new Attribute($element['#attributes']) : '';
  84
  85     // An HTML tag should not contain any special characters. Escape them to
  86     // ensure this cannot be abused.
  87     $escaped_tag = HtmlUtility::escape($element['#tag']);
  88     $open_tag = '<' . $escaped_tag . $attributes;
  89     $close_tag = '</' . $escaped_tag . ">\n";
  90     // Construct a void element.
  91     if (in_array($element['#tag'], self::$voidElements)) {
  92       $open_tag .= ' />';
  93       $close_tag = "\n";
  94     }
  95     // Construct all other elements.
  96     else {
  97       $open_tag .= '>';
  98       $markup = $element['#value'] instanceof MarkupInterface ? $element['#value'] : Xss::filterAdmin($element['#value']);
  99       $element['#markup'] = Markup::create($markup);
 100     }
 101     $prefix = isset($element['#prefix']) ? $element['#prefix'] . $open_tag : $open_tag;
 102     $suffix = isset($element['#suffix']) ? $close_tag . $element['#suffix'] : $close_tag;
 103     if (!empty($element['#noscript'])) {
 104       $prefix = '<noscript>' . $prefix;
 105       $suffix .= '</noscript>';
 106     }
 107     $element['#prefix'] = Markup::create($prefix);
 108     $element['#suffix'] = Markup::create($suffix);
 109     return $element;
 110   }
 111
 112   /**
 113    * Pre-render callback: Renders #browsers into #prefix and #suffix.
 114    *
 115    * @param array $element
 116    *   A render array with a '#browsers' property. The '#browsers' property can
 117    *   contain any or all of the following keys:
 118    *   - 'IE': If FALSE, the element is not rendered by Internet Explorer. If
 119    *     TRUE, the element is rendered by Internet Explorer. Can also be a string
 120    *     containing an expression for Internet Explorer to evaluate as part of a
 121    *     conditional comment. For example, this can be set to 'lt IE 7' for the
 122    *     element to be rendered in Internet Explorer 6, but not in Internet
 123    *     Explorer 7 or higher. Defaults to TRUE.
 124    *   - '!IE': If FALSE, the element is not rendered by browsers other than
 125    *     Internet Explorer. If TRUE, the element is rendered by those browsers.
 126    *     Defaults to TRUE.
 127    *   Examples:
 128    *   - To render an element in all browsers, '#browsers' can be left out or set
 129    *     to array('IE' => TRUE, '!IE' => TRUE).
 130    *   - To render an element in Internet Explorer only, '#browsers' can be set
 131    *     to array('!IE' => FALSE).
 132    *   - To render an element in Internet Explorer 6 only, '#browsers' can be set
 133    *     to array('IE' => 'lt IE 7', '!IE' => FALSE).
 134    *   - To render an element in Internet Explorer 8 and higher and in all other
 135    *     browsers, '#browsers' can be set to array('IE' => 'gte IE 8').
 136    *
 137    * @return array
 138    *   The passed-in element with markup for conditional comments potentially
 139    *   added to '#prefix' and '#suffix'.
 140    */
 141   public static function preRenderConditionalComments($element) {
 142     $browsers = isset($element['#browsers']) ? $element['#browsers'] : [];
 143     $browsers += [
 144       'IE' => TRUE,
 145       '!IE' => TRUE,
 146     ];
 147
 148     // If rendering in all browsers, no need for conditional comments.
 149     if ($browsers['IE'] === TRUE && $browsers['!IE']) {
 150       return $element;
 151     }
 152
 153     // Determine the conditional comment expression for Internet Explorer to
 154     // evaluate.
 155     if ($browsers['IE'] === TRUE) {
 156       $expression = 'IE';
 157     }
 158     elseif ($browsers['IE'] === FALSE) {
 159       $expression = '!IE';
 160     }
 161     else {
 162       // The IE expression might contain some user input data.
 163       $expression = Xss::filterAdmin($browsers['IE']);
 164     }
 165
 166     // If the #prefix and #suffix properties are used, wrap them with
 167     // conditional comment markup. The conditional comment expression is
 168     // evaluated by Internet Explorer only. To control the rendering by other
 169     // browsers, use either the "downlevel-hidden" or "downlevel-revealed"
 170     // technique. See http://wikipedia.org/wiki/Conditional_comment
 171     // for details.
 172
 173     // Ensure what we are dealing with is safe.
 174     // This would be done later anyway in drupal_render().
 175     $prefix = isset($element['#prefix']) ? $element['#prefix'] : '';
 176     if ($prefix && !($prefix instanceof MarkupInterface)) {
 177       $prefix = Xss::filterAdmin($prefix);
 178     }
 179     $suffix = isset($element['#suffix']) ? $element['#suffix'] : '';
 180     if ($suffix && !($suffix instanceof MarkupInterface)) {
 181       $suffix = Xss::filterAdmin($suffix);
 182     }
 183
 184     // We ensured above that $expression is either a string we created or is
 185     // admin XSS filtered, and that $prefix and $suffix are also admin XSS
 186     // filtered if they are unsafe. Thus, all these strings are safe.
 187     if (!$browsers['!IE']) {
 188       // "downlevel-hidden".
 189       $element['#prefix'] = Markup::create("\n<!--[if $expression]>\n" . $prefix);
 190       $element['#suffix'] = Markup::create($suffix . "<![endif]-->\n");
 191     }
 192     else {
 193       // "downlevel-revealed".
 194       $element['#prefix'] = Markup::create("\n<!--[if $expression]><!-->\n" . $prefix);
 195       $element['#suffix'] = Markup::create($suffix . "<!--<![endif]-->\n");
 196     }
 197
 198     return $element;
 199   }
 200
 201 }