CRM/Core/Region.php

   1 <?php
   2
   3 /**
   4  * Maintain a set of markup/templates to inject inside various regions
   5  */
   6 class CRM_Core_Region {
   7   static private $_instances = NULL;
   8
   9   /**
  10    * Obtain the content for a given region.
  11    *
  12    * @param string $name
  13    * @param bool $autocreate
  14    *   Whether to automatically create an empty region.
  15    * @return CRM_Core_Region
  16    */
  17   public static function &instance($name, $autocreate = TRUE) {
  18     if ($autocreate && !isset(self::$_instances[$name])) {
  19       self::$_instances[$name] = new CRM_Core_Region($name);
  20     }
  21     return self::$_instances[$name];
  22   }
  23
  24   /**
  25    * Symbolic name of this region
  26    *
  27    * @var string
  28    */
  29   public $_name;
  30
  31   /**
  32    * List of snippets to inject within region.
  33    *
  34    * e.g. $this->_snippets[3]['type'] = 'template';
  35    *
  36    * @var array
  37    */
  38   public $_snippets;
  39
  40   /**
  41    * Whether the snippets array has been sorted
  42    *
  43    * @var bool
  44    */
  45   public $_isSorted;
  46
  47   /**
  48    * @param string $name
  49    */
  50   public function __construct($name) {
  51     // Templates injected into regions should normally be file names, but sometimes inline notation is handy.
  52     require_once 'CRM/Core/Smarty/resources/String.php';
  53     civicrm_smarty_register_string_resource();
  54
  55     $this->_name = $name;
  56     $this->_snippets = [];
  57
  58     // Placeholder which represents any of the default content generated by the main Smarty template
  59     $this->add([
  60       'name' => 'default',
  61       'type' => 'markup',
  62       'markup' => '',
  63       'weight' => 0,
  64     ]);
  65     $this->_isSorted = TRUE;
  66   }
  67
  68   /**
  69    * Add a snippet of content to a region.
  70    *
  71    * ```
  72    * CRM_Core_Region::instance('page-header')->add(array(
  73    *   'markup' => '<div style="color:red">Hello!</div>',
  74    * ));
  75    * CRM_Core_Region::instance('page-header')->add(array(
  76    *   'script' => 'alert("Hello");',
  77    * ));
  78    * CRM_Core_Region::instance('page-header')->add(array(
  79    *   'template' => 'CRM/Myextension/Extra.tpl',
  80    * ));
  81    * CRM_Core_Region::instance('page-header')->add(array(
  82    *   'callback' => 'myextension_callback_function',
  83    * ));
  84    * ```
  85    *
  86    * Note: This function does not perform any extra encoding of markup, script code, or etc. If
  87    * you're passing in user-data, you must clean it yourself.
  88    *
  89    * @param array $snippet
  90    *   Array; keys:.
  91    *   - type: string (auto-detected for markup, template, callback, script, scriptUrl, jquery, style, styleUrl)
  92    *   - name: string, optional
  93    *   - weight: int, optional; default=1
  94    *   - disabled: int, optional; default=0
  95    *   - markup: string, HTML; required (for type==markup)
  96    *   - template: string, path; required (for type==template)
  97    *   - callback: mixed; required (for type==callback)
  98    *   - arguments: array, optional (for type==callback)
  99    *   - script: string, Javascript code
 100    *   - scriptUrl: string, URL of a Javascript file
 101    *   - jquery: string, Javascript code which runs inside a jQuery(function($){...}); block
 102    *   - style: string, CSS code
 103    *   - styleUrl: string, URL of a CSS file
 104    *
 105    * @return array
 106    */
 107   public function add($snippet) {
 108     static $types = ['markup', 'template', 'callback', 'scriptUrl', 'script', 'jquery', 'style', 'styleUrl'];
 109     $defaults = [
 110       'region' => $this->_name,
 111       'weight' => 1,
 112       'disabled' => FALSE,
 113     ];
 114     $snippet += $defaults;
 115     if (!isset($snippet['type'])) {
 116       foreach ($types as $type) {
 117         // auto-detect
 118         if (isset($snippet[$type])) {
 119           $snippet['type'] = $type;
 120           break;
 121         }
 122       }
 123     }
 124     if (!isset($snippet['name'])) {
 125       $snippet['name'] = count($this->_snippets);
 126     }
 127
 128     $this->_snippets[$snippet['name']] = $snippet;
 129     $this->_isSorted = FALSE;
 130     return $snippet;
 131   }
 132
 133   /**
 134    * @param string $name
 135    * @param $snippet
 136    */
 137   public function update($name, $snippet) {
 138     $this->_snippets[$name] = array_merge($this->_snippets[$name], $snippet);
 139     $this->_isSorted = FALSE;
 140   }
 141
 142   /**
 143    * Get snippet.
 144    *
 145    * @param string $name
 146    *
 147    * @return mixed
 148    */
 149   public function get($name) {
 150     return !empty($this->_snippets[$name]) ? $this->_snippets[$name] : NULL;
 151   }
 152
 153   /**
 154    * Render all the snippets in a region.
 155    *
 156    * @param string $default
 157    *   HTML, the initial content of the region.
 158    * @param bool $allowCmsOverride
 159    *   Allow CMS to override rendering of region.
 160    * @return string, HTML
 161    */
 162   public function render($default, $allowCmsOverride = TRUE) {
 163     // $default is just another part of the region
 164     if (is_array($this->_snippets['default'])) {
 165       $this->_snippets['default']['markup'] = $default;
 166     }
 167     // We hand as much of the work off to the CMS as possible
 168     $cms = CRM_Core_Config::singleton()->userSystem;
 169
 170     if (!$this->_isSorted) {
 171       uasort($this->_snippets, ['CRM_Core_Region', '_cmpSnippet']);
 172       $this->_isSorted = TRUE;
 173     }
 174
 175     $smarty = CRM_Core_Smarty::singleton();
 176     $html = '';
 177     foreach ($this->_snippets as $snippet) {
 178       if ($snippet['disabled']) {
 179         continue;
 180       }
 181       switch ($snippet['type']) {
 182         case 'markup':
 183           $html .= $snippet['markup'];
 184           break;
 185
 186         case 'template':
 187           $tmp = $smarty->get_template_vars('snippet');
 188           $smarty->assign('snippet', $snippet);
 189           $html .= $smarty->fetch($snippet['template']);
 190           $smarty->assign('snippet', $tmp);
 191           break;
 192
 193         case 'callback':
 194           $args = $snippet['arguments'] ?? array(&$snippet, &$html);
 195           $html .= call_user_func_array($snippet['callback'], $args);
 196           break;
 197
 198         case 'scriptUrl':
 199           if (!$allowCmsOverride || !$cms->addScriptUrl($snippet['scriptUrl'], $this->_name)) {
 200             $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
 201           }
 202           break;
 203
 204         case 'jquery':
 205           $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
 206           // no break - continue processing as script
 207         case 'script':
 208           if (!$allowCmsOverride || !$cms->addScript($snippet['script'], $this->_name)) {
 209             $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
 210           }
 211           break;
 212
 213         case 'styleUrl':
 214           if (!$allowCmsOverride || !$cms->addStyleUrl($snippet['styleUrl'], $this->_name)) {
 215             $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
 216           }
 217           break;
 218
 219         case 'style':
 220           if (!$allowCmsOverride || !$cms->addStyle($snippet['style'], $this->_name)) {
 221             $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
 222           }
 223           break;
 224
 225         default:
 226           require_once 'CRM/Core/Error.php';
 227           CRM_Core_Error::fatal(ts('Snippet type %1 is unrecognized',
 228             [1 => $snippet['type']]));
 229       }
 230     }
 231     return $html;
 232   }
 233
 234   /**
 235    * @param $a
 236    * @param $b
 237    *
 238    * @return int
 239    */
 240   public static function _cmpSnippet($a, $b) {
 241     if ($a['weight'] < $b['weight']) {
 242       return -1;
 243     }
 244     if ($a['weight'] > $b['weight']) {
 245       return 1;
 246     }
 247     // fallback to name sort; don't really want to do this, but it makes results more stable
 248     if ($a['name'] < $b['name']) {
 249       return -1;
 250     }
 251     if ($a['name'] > $b['name']) {
 252       return 1;
 253     }
 254     return 0;
 255   }
 256
 257   /**
 258    * Add block of static HTML to a region.
 259    *
 260    * @param string $markup
 261    *   HTML.
 262    *
 263    * public function addMarkup($markup) {
 264    * return $this->add(array(
 265    * 'type' => 'markup',
 266    * 'markup' => $markup,
 267    * ));
 268    * }
 269    *
 270    * /**
 271    * Add a Smarty template file to a region.
 272    *
 273    * Note: File is not evaluated until the page is rendered
 274    *
 275    * @param string $template
 276    *   Path to the Smarty template file.
 277    *
 278    * public function addTemplate($template) {
 279    * return $this->add(array(
 280    * 'type' => 'template',
 281    * 'template' => $template,
 282    * ));
 283    * }
 284    *
 285    * /**
 286    * Use a callback function to extend a region.
 287    *
 288    * @param mixed $callback
 289    * @param array $arguments
 290    *   Optional, array of parameters for callback; if omitted, the default arguments are ($snippetSpec, $html).
 291    *
 292    * public function addCallback($callback, $arguments = FALSE) {
 293    * return $this->add(array(
 294    * 'type' => 'callback',
 295    * 'callback' => $callback,
 296    * 'arguments' => $arguments,
 297    * ));
 298    * }
 299    */
 300
 301 }