4 * Maintain a set of markup/templates to inject inside various regions
6 class CRM_Core_Region
{
7 static private $_instances = NULL;
10 * Obtain the content for a given region
13 * @param bool $autocreate whether to automatically create an empty region
14 * @return CRM_Core_Region
16 static function &instance($name, $autocreate = TRUE) {
17 if ( $autocreate && ! isset( self
::$_instances[$name] ) ) {
18 self
::$_instances[$name] = new CRM_Core_Region($name);
20 return self
::$_instances[$name];
24 * Symbolic name of this region
31 * List of snippets to inject within region
33 * @var array; e.g. $this->_snippets[3]['type'] = 'template';
38 * Whether the snippets array has been sorted
47 public function __construct($name) {
48 // Templates injected into regions should normally be file names, but sometimes inline notation is handy.
49 require_once 'CRM/Core/Smarty/resources/String.php';
50 civicrm_smarty_register_string_resource( );
53 $this->_snippets
= array();
55 // Placeholder which represents any of the default content generated by the main Smarty template
62 $this->_isSorted
= TRUE;
66 * Add a snippet of content to a region
69 * CRM_Core_Region::instance('page-header')->add(array(
70 * 'markup' => '<div style="color:red">Hello!</div>',
72 * CRM_Core_Region::instance('page-header')->add(array(
73 * 'script' => 'alert("Hello");',
75 * CRM_Core_Region::instance('page-header')->add(array(
76 * 'template' => 'CRM/Myextension/Extra.tpl',
78 * CRM_Core_Region::instance('page-header')->add(array(
79 * 'callback' => 'myextension_callback_function',
83 * Note: This function does not perform any extra encoding of markup, script code, or etc. If
84 * you're passing in user-data, you must clean it yourself.
86 * @param $snippet array; keys:
87 * - type: string (auto-detected for markup, template, callback, script, scriptUrl, jquery, style, styleUrl)
88 * - name: string, optional
89 * - weight: int, optional; default=1
90 * - disabled: int, optional; default=0
91 * - markup: string, HTML; required (for type==markup)
92 * - template: string, path; required (for type==template)
93 * - callback: mixed; required (for type==callback)
94 * - arguments: array, optional (for type==callback)
95 * - script: string, Javascript code
96 * - scriptUrl: string, URL of a Javascript file
97 * - jquery: string, Javascript code which runs inside a jQuery(function($){...}); block
98 * - style: string, CSS code
99 * - styleUrl: string, URL of a CSS file
103 public function add($snippet) {
104 static $types = array('markup', 'template', 'callback', 'scriptUrl', 'script', 'jquery', 'style', 'styleUrl');
106 'region' => $this->_name
,
110 $snippet +
= $defaults;
111 if (!isset($snippet['type'])) {
112 foreach ($types as $type) {
114 if (isset($snippet[$type])) {
115 $snippet['type'] = $type;
120 if (!isset($snippet['name'])) {
121 $snippet['name'] = count($this->_snippets
);
123 $this->_snippets
[ $snippet['name'] ] = $snippet;
124 $this->_isSorted
= FALSE;
129 * @param string $name
132 public function update($name, $snippet) {
133 $this->_snippets
[$name] = array_merge($this->_snippets
[$name], $snippet);
134 $this->_isSorted
= FALSE;
138 * @param string $name
142 public function &get($name) {
143 return @$this->_snippets
[$name];
147 * Render all the snippets in a region
149 * @param string $default HTML, the initial content of the region
150 * @param bool $allowCmsOverride allow CMS to override rendering of region
151 * @return string, HTML
153 public function render($default, $allowCmsOverride = TRUE) {
154 // $default is just another part of the region
155 if (is_array($this->_snippets
['default'])) {
156 $this->_snippets
['default']['markup'] = $default;
158 // We hand as much of the work off to the CMS as possible
159 $cms = CRM_Core_Config
::singleton()->userSystem
;
161 if (!$this->_isSorted
) {
162 uasort($this->_snippets
, array('CRM_Core_Region', '_cmpSnippet'));
163 $this->_isSorted
= TRUE;
166 $smarty = CRM_Core_Smarty
::singleton();
168 foreach ($this->_snippets
as $snippet) {
169 if ($snippet['disabled']) {
172 switch($snippet['type']) {
174 $html .= $snippet['markup'];
177 $tmp = $smarty->get_template_vars('snippet');
178 $smarty->assign('snippet', $snippet);
179 $html .= $smarty->fetch($snippet['template']);
180 $smarty->assign('snippet', $tmp);
183 $args = isset($snippet['arguments']) ?
$snippet['arguments'] : array(&$snippet, &$html);
184 $html .= call_user_func_array($snippet['callback'], $args);
187 if (!$allowCmsOverride ||
!$cms->addScriptUrl($snippet['scriptUrl'], $this->_name
)) {
188 $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
192 $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
193 // no break - continue processing as script
195 if (!$allowCmsOverride ||
!$cms->addScript($snippet['script'], $this->_name
)) {
196 $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
200 if (!$allowCmsOverride ||
!$cms->addStyleUrl($snippet['styleUrl'], $this->_name
)) {
201 $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
205 if (!$allowCmsOverride ||
!$cms->addStyle($snippet['style'], $this->_name
)) {
206 $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
210 require_once 'CRM/Core/Error.php';
211 CRM_Core_Error
::fatal( ts( 'Snippet type %1 is unrecognized',
212 array( 1 => $snippet['type'] ) ) );
224 static function _cmpSnippet($a, $b) {
225 if ($a['weight'] < $b['weight']) return -1;
226 if ($a['weight'] > $b['weight']) return 1;
227 // fallback to name sort; don't really want to do this, but it makes results more stable
228 if ($a['name'] < $b['name']) return -1;
229 if ($a['name'] > $b['name']) return 1;
234 * Add block of static HTML to a region
236 * @param string $markup HTML
238 public function addMarkup($markup) {
239 return $this->add(array(
246 * Add a Smarty template file to a region
248 * Note: File is not evaluated until the page is rendered
250 * @param string $template path to the Smarty template file
252 public function addTemplate($template) {
253 return $this->add(array(
254 'type' => 'template',
255 'template' => $template,
260 * Use a callback function to extend a region
262 * @param mixed $callback
263 * @param array $arguments optional, array of parameters for callback; if omitted, the default arguments are ($snippetSpec, $html)
265 public function addCallback($callback, $arguments = FALSE) {
266 return $this->add(array(
267 'type' => 'callback',
268 'callback' => $callback,
269 'arguments' => $arguments,