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 $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     $this->_snippets[ $snippet['name'] ] = $snippet;
 126     $this->_isSorted = FALSE;
 127     return $snippet;
 128   }
 129
 130   /**
 131    * @param string $name
 132    * @param $snippet
 133    */
 134   public function update($name, $snippet) {
 135     $this->_snippets[$name] = array_merge($this->_snippets[$name], $snippet);
 136     $this->_isSorted = FALSE;
 137   }
 138
 139   /**
 140    * @param string $name
 141    *
 142    * @return mixed
 143    */
 144   public function &get($name) {
 145     return @$this->_snippets[$name];
 146   }
 147
 148   /**
 149    * Render all the snippets in a region
 150    *
 151    * @param string $default
 152    *   HTML, the initial content of the region.
 153    * @param bool $allowCmsOverride
 154    *   Allow CMS to override rendering of region.
 155    * @return string, HTML
 156    */
 157   public function render($default, $allowCmsOverride = TRUE) {
 158     // $default is just another part of the region
 159     if (is_array($this->_snippets['default'])) {
 160       $this->_snippets['default']['markup'] = $default;
 161     }
 162     // We hand as much of the work off to the CMS as possible
 163     $cms = CRM_Core_Config::singleton()->userSystem;
 164
 165     if (!$this->_isSorted) {
 166       uasort($this->_snippets, array('CRM_Core_Region', '_cmpSnippet'));
 167       $this->_isSorted = TRUE;
 168     }
 169
 170     $smarty = CRM_Core_Smarty::singleton();
 171     $html = '';
 172     foreach ($this->_snippets as $snippet) {
 173       if ($snippet['disabled']) {
 174         continue;
 175       }
 176       switch($snippet['type']) {
 177         case 'markup':
 178           $html .= $snippet['markup'];
 179           break;
 180         case 'template':
 181           $tmp = $smarty->get_template_vars('snippet');
 182           $smarty->assign('snippet', $snippet);
 183           $html .= $smarty->fetch($snippet['template']);
 184           $smarty->assign('snippet', $tmp);
 185           break;
 186         case 'callback':
 187           $args = isset($snippet['arguments']) ? $snippet['arguments'] : array(&$snippet, &$html);
 188           $html .= call_user_func_array($snippet['callback'], $args);
 189           break;
 190         case 'scriptUrl':
 191           if (!$allowCmsOverride || !$cms->addScriptUrl($snippet['scriptUrl'], $this->_name)) {
 192             $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
 193           }
 194           break;
 195         case 'jquery':
 196           $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
 197           // no break - continue processing as script
 198         case 'script':
 199           if (!$allowCmsOverride || !$cms->addScript($snippet['script'], $this->_name)) {
 200             $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
 201           }
 202           break;
 203         case 'styleUrl':
 204           if (!$allowCmsOverride || !$cms->addStyleUrl($snippet['styleUrl'], $this->_name)) {
 205             $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
 206           }
 207           break;
 208         case 'style':
 209           if (!$allowCmsOverride || !$cms->addStyle($snippet['style'], $this->_name)) {
 210             $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
 211           }
 212           break;
 213         default:
 214           require_once 'CRM/Core/Error.php';
 215           CRM_Core_Error::fatal( ts( 'Snippet type %1 is unrecognized',
 216                      array( 1 => $snippet['type'] ) ) );
 217       }
 218     }
 219     return $html;
 220   }
 221
 222   /**
 223    * @param $a
 224    * @param $b
 225    *
 226    * @return int
 227    */
 228   public static function _cmpSnippet($a, $b) {
 229     if ($a['weight'] < $b['weight']) return -1;
 230     if ($a['weight'] > $b['weight']) return 1;
 231     // fallback to name sort; don't really want to do this, but it makes results more stable
 232     if ($a['name'] < $b['name']) return -1;
 233     if ($a['name'] > $b['name']) return 1;
 234     return 0;
 235   }
 236
 237   /**
 238    * Add block of static HTML to a region
 239    *
 240    * @param string $markup
 241    *   HTML.
 242    *
 243   public function addMarkup($markup) {
 244     return $this->add(array(
 245       'type' => 'markup',
 246       'markup' => $markup,
 247     ));
 248   }
 249
 250   /**
 251    * Add a Smarty template file to a region
 252    *
 253    * Note: File is not evaluated until the page is rendered
 254    *
 255    * @param string $template
 256    *   Path to the Smarty template file.
 257    *
 258   public function addTemplate($template) {
 259     return $this->add(array(
 260       'type' => 'template',
 261       'template' => $template,
 262     ));
 263   }
 264
 265   /**
 266    * Use a callback function to extend a region
 267    *
 268    * @param mixed $callback
 269    * @param array $arguments
 270    *   Optional, array of parameters for callback; if omitted, the default arguments are ($snippetSpec, $html).
 271    *
 272   public function addCallback($callback, $arguments = FALSE) {
 273     return $this->add(array(
 274       'type' => 'callback',
 275       'callback' => $callback,
 276       'arguments' => $arguments,
 277     ));
 278   }
 279   */
 280 }