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