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 * @var array; e.g. $this->_snippets[3]['type'] = 'template';
39 * Whether the snippets array has been sorted
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();
54 $this->_snippets
= array();
56 // Placeholder which represents any of the default content generated by the main Smarty template
63 $this->_isSorted
= TRUE;
67 * Add a snippet of content to a region.
70 * CRM_Core_Region::instance('page-header')->add(array(
71 * 'markup' => '<div style="color:red">Hello!</div>',
73 * CRM_Core_Region::instance('page-header')->add(array(
74 * 'script' => 'alert("Hello");',
76 * CRM_Core_Region::instance('page-header')->add(array(
77 * 'template' => 'CRM/Myextension/Extra.tpl',
79 * CRM_Core_Region::instance('page-header')->add(array(
80 * 'callback' => 'myextension_callback_function',
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.
87 * @param array $snippet
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
105 public function add($snippet) {
106 static $types = array('markup', 'template', 'callback', 'scriptUrl', 'script', 'jquery', 'style', 'styleUrl');
108 'region' => $this->_name
,
112 $snippet +
= $defaults;
113 if (!isset($snippet['type'])) {
114 foreach ($types as $type) {
116 if (isset($snippet[$type])) {
117 $snippet['type'] = $type;
122 if (!isset($snippet['name'])) {
123 $snippet['name'] = count($this->_snippets
);
125 $this->_snippets
[$snippet['name']] = $snippet;
126 $this->_isSorted
= FALSE;
131 * @param string $name
134 public function update($name, $snippet) {
135 $this->_snippets
[$name] = array_merge($this->_snippets
[$name], $snippet);
136 $this->_isSorted
= FALSE;
140 * @param string $name
144 public function &get($name) {
145 return @$this->_snippets
[$name];
149 * Render all the snippets in a region.
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
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;
162 // We hand as much of the work off to the CMS as possible
163 $cms = CRM_Core_Config
::singleton()->userSystem
;
165 if (!$this->_isSorted
) {
166 uasort($this->_snippets
, array('CRM_Core_Region', '_cmpSnippet'));
167 $this->_isSorted
= TRUE;
170 $smarty = CRM_Core_Smarty
::singleton();
172 foreach ($this->_snippets
as $snippet) {
173 if ($snippet['disabled']) {
176 switch ($snippet['type']) {
178 $html .= $snippet['markup'];
182 $tmp = $smarty->get_template_vars('snippet');
183 $smarty->assign('snippet', $snippet);
184 $html .= $smarty->fetch($snippet['template']);
185 $smarty->assign('snippet', $tmp);
189 $args = isset($snippet['arguments']) ?
$snippet['arguments'] : array(&$snippet, &$html);
190 $html .= call_user_func_array($snippet['callback'], $args);
194 if (!$allowCmsOverride ||
!$cms->addScriptUrl($snippet['scriptUrl'], $this->_name
)) {
195 $html .= sprintf("<script type=\"text/javascript\" src=\"%s\">\n</script>\n", $snippet['scriptUrl']);
200 $snippet['script'] = sprintf("CRM.\$(function(\$) {\n%s\n});", $snippet['jquery']);
201 // no break - continue processing as script
203 if (!$allowCmsOverride ||
!$cms->addScript($snippet['script'], $this->_name
)) {
204 $html .= sprintf("<script type=\"text/javascript\">\n%s\n</script>\n", $snippet['script']);
209 if (!$allowCmsOverride ||
!$cms->addStyleUrl($snippet['styleUrl'], $this->_name
)) {
210 $html .= sprintf("<link href=\"%s\" rel=\"stylesheet\" type=\"text/css\"/>\n", $snippet['styleUrl']);
215 if (!$allowCmsOverride ||
!$cms->addStyle($snippet['style'], $this->_name
)) {
216 $html .= sprintf("<style type=\"text/css\">\n%s\n</style>\n", $snippet['style']);
221 require_once 'CRM/Core/Error.php';
222 CRM_Core_Error
::fatal(ts('Snippet type %1 is unrecognized',
223 array(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']) {
253 * Add block of static HTML to a region.
255 * @param string $markup
258 * public function addMarkup($markup) {
259 * return $this->add(array(
260 * 'type' => 'markup',
261 * 'markup' => $markup,
266 * Add a Smarty template file to a region.
268 * Note: File is not evaluated until the page is rendered
270 * @param string $template
271 * Path to the Smarty template file.
273 * public function addTemplate($template) {
274 * return $this->add(array(
275 * 'type' => 'template',
276 * 'template' => $template,
281 * Use a callback function to extend a region.
283 * @param mixed $callback
284 * @param array $arguments
285 * Optional, array of parameters for callback; if omitted, the default arguments are ($snippetSpec, $html).
287 * public function addCallback($callback, $arguments = FALSE) {
288 * return $this->add(array(
289 * 'type' => 'callback',
290 * 'callback' => $callback,
291 * 'arguments' => $arguments,