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) {
52 $this->_snippets
= [];
54 // Placeholder which represents any of the default content generated by the main Smarty template
61 $this->_isSorted
= TRUE;
65 * Add a snippet of content to a region.
68 * CRM_Core_Region::instance('page-header')->add(array(
69 * 'markup' => '<div style="color:red">Hello!</div>',
71 * CRM_Core_Region::instance('page-header')->add(array(
72 * 'script' => 'alert("Hello");',
74 * CRM_Core_Region::instance('page-header')->add(array(
75 * 'template' => 'CRM/Myextension/Extra.tpl',
77 * CRM_Core_Region::instance('page-header')->add(array(
78 * 'callback' => 'myextension_callback_function',
82 * Note: This function does not perform any extra encoding of markup, script code, or etc. If
83 * you're passing in user-data, you must clean it yourself.
85 * @param array $snippet
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 = ['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
);
124 $this->_snippets
[$snippet['name']] = $snippet;
125 $this->_isSorted
= FALSE;
130 * @param string $name
133 public function update($name, $snippet) {
134 $this->_snippets
[$name] = array_merge($this->_snippets
[$name], $snippet);
135 $this->_isSorted
= FALSE;
141 * @param string $name
145 public function get($name) {
146 return !empty($this->_snippets
[$name]) ?
$this->_snippets
[$name] : NULL;
150 * Render all the snippets in a region.
152 * @param string $default
153 * HTML, the initial content of the region.
154 * @param bool $allowCmsOverride
155 * Allow CMS to override rendering of region.
156 * @return string, HTML
158 public function render($default, $allowCmsOverride = TRUE) {
159 // $default is just another part of the region
160 if (is_array($this->_snippets
['default'])) {
161 $this->_snippets
['default']['markup'] = $default;
163 // We hand as much of the work off to the CMS as possible
164 $cms = CRM_Core_Config
::singleton()->userSystem
;
166 if (!$this->_isSorted
) {
167 uasort($this->_snippets
, ['CRM_Core_Region', '_cmpSnippet']);
168 $this->_isSorted
= TRUE;
171 $smarty = CRM_Core_Smarty
::singleton();
173 foreach ($this->_snippets
as $snippet) {
174 if ($snippet['disabled']) {
177 switch ($snippet['type']) {
179 $html .= $snippet['markup'];
183 $tmp = $smarty->get_template_vars('snippet');
184 $smarty->assign('snippet', $snippet);
185 $html .= $smarty->fetch($snippet['template']);
186 $smarty->assign('snippet', $tmp);
190 $args = $snippet['arguments'] ??
array(&$snippet, &$html);
191 $html .= call_user_func_array($snippet['callback'], $args);
195 if (!$allowCmsOverride ||
!$cms->addScriptUrl($snippet['scriptUrl'], $this->_name
)) {
196 $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
201 $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
202 // no break - continue processing as script
204 if (!$allowCmsOverride ||
!$cms->addScript($snippet['script'], $this->_name
)) {
205 $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
210 if (!$allowCmsOverride ||
!$cms->addStyleUrl($snippet['styleUrl'], $this->_name
)) {
211 $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
216 if (!$allowCmsOverride ||
!$cms->addStyle($snippet['style'], $this->_name
)) {
217 $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
222 throw new CRM_Core_Exception(ts('Snippet type %1 is unrecognized',
223 [1 => $snippet['type']]));
235 public static function _cmpSnippet($a, $b) {
236 if ($a['weight'] < $b['weight']) {
239 if ($a['weight'] > $b['weight']) {
242 // fallback to name sort; don't really want to do this, but it makes results more stable
243 if ($a['name'] < $b['name']) {
246 if ($a['name'] > $b['name']) {