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