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
14 * Whether to automatically create an empty region.
15 * @return CRM_Core_Region
17 public static function &instance($name, $autocreate = TRUE) {
18 if ($autocreate && !isset(self
::$_instances[$name])) {
19 self
::$_instances[$name] = new CRM_Core_Region($name);
21 return self
::$_instances[$name];
25 * Symbolic name of this region
32 * List of snippets to inject within region.
34 * e.g. $this->_snippets[3]['type'] = 'template';
41 * Whether the snippets array has been sorted
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();
56 $this->_snippets
= [];
58 // Placeholder which represents any of the default content generated by the main Smarty template
65 $this->_isSorted
= TRUE;
69 * Add a snippet of content to a region.
72 * CRM_Core_Region::instance('page-header')->add(array(
73 * 'markup' => '<div style="color:red">Hello!</div>',
75 * CRM_Core_Region::instance('page-header')->add(array(
76 * 'script' => 'alert("Hello");',
78 * CRM_Core_Region::instance('page-header')->add(array(
79 * 'template' => 'CRM/Myextension/Extra.tpl',
81 * CRM_Core_Region::instance('page-header')->add(array(
82 * 'callback' => 'myextension_callback_function',
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.
89 * @param array $snippet
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
107 public function add($snippet) {
108 static $types = ['markup', 'template', 'callback', 'scriptUrl', 'script', 'jquery', 'style', 'styleUrl'];
110 'region' => $this->_name
,
114 $snippet +
= $defaults;
115 if (!isset($snippet['type'])) {
116 foreach ($types as $type) {
118 if (isset($snippet[$type])) {
119 $snippet['type'] = $type;
124 if (!isset($snippet['name'])) {
125 $snippet['name'] = count($this->_snippets
);
128 $this->_snippets
[$snippet['name']] = $snippet;
129 $this->_isSorted
= FALSE;
134 * @param string $name
137 public function update($name, $snippet) {
138 $this->_snippets
[$name] = array_merge($this->_snippets
[$name], $snippet);
139 $this->_isSorted
= FALSE;
145 * @param string $name
149 public function get($name) {
150 return !empty($this->_snippets
[$name]) ?
$this->_snippets
[$name] : NULL;
154 * Render all the snippets in a region.
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
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;
167 // We hand as much of the work off to the CMS as possible
168 $cms = CRM_Core_Config
::singleton()->userSystem
;
170 if (!$this->_isSorted
) {
171 uasort($this->_snippets
, ['CRM_Core_Region', '_cmpSnippet']);
172 $this->_isSorted
= TRUE;
175 $smarty = CRM_Core_Smarty
::singleton();
177 foreach ($this->_snippets
as $snippet) {
178 if ($snippet['disabled']) {
181 switch ($snippet['type']) {
183 $html .= $snippet['markup'];
187 $tmp = $smarty->get_template_vars('snippet');
188 $smarty->assign('snippet', $snippet);
189 $html .= $smarty->fetch($snippet['template']);
190 $smarty->assign('snippet', $tmp);
194 $args = $snippet['arguments'] ??
array(&$snippet, &$html);
195 $html .= call_user_func_array($snippet['callback'], $args);
199 if (!$allowCmsOverride ||
!$cms->addScriptUrl($snippet['scriptUrl'], $this->_name
)) {
200 $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
205 $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
206 // no break - continue processing as script
208 if (!$allowCmsOverride ||
!$cms->addScript($snippet['script'], $this->_name
)) {
209 $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
214 if (!$allowCmsOverride ||
!$cms->addStyleUrl($snippet['styleUrl'], $this->_name
)) {
215 $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
220 if (!$allowCmsOverride ||
!$cms->addStyle($snippet['style'], $this->_name
)) {
221 $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
226 require_once 'CRM/Core/Error.php';
227 CRM_Core_Error
::fatal(ts('Snippet type %1 is unrecognized',
228 [1 => $snippet['type']]));
240 public static function _cmpSnippet($a, $b) {
241 if ($a['weight'] < $b['weight']) {
244 if ($a['weight'] > $b['weight']) {
247 // fallback to name sort; don't really want to do this, but it makes results more stable
248 if ($a['name'] < $b['name']) {
251 if ($a['name'] > $b['name']) {
258 * Add block of static HTML to a region.
260 * @param string $markup
263 * public function addMarkup($markup) {
264 * return $this->add(array(
265 * 'type' => 'markup',
266 * 'markup' => $markup,
271 * Add a Smarty template file to a region.
273 * Note: File is not evaluated until the page is rendered
275 * @param string $template
276 * Path to the Smarty template file.
278 * public function addTemplate($template) {
279 * return $this->add(array(
280 * 'type' => 'template',
281 * 'template' => $template,
286 * Use a callback function to extend a region.
288 * @param mixed $callback
289 * @param array $arguments
290 * Optional, array of parameters for callback; if omitted, the default arguments are ($snippetSpec, $html).
292 * public function addCallback($callback, $arguments = FALSE) {
293 * return $this->add(array(
294 * 'type' => 'callback',
295 * 'callback' => $callback,
296 * 'arguments' => $arguments,