3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
19 * A Page is basically data in a nice pretty format.
21 * Pages should not have any form actions / elements in them. If they
22 * do, make sure you use CRM_Core_Form and the related structures. You can
23 * embed simple forms in Page and do your own form handling.
29 * The name of the page (auto generated from class name)
36 * The title associated with this page.
43 * A page can have multiple modes. (i.e. displays
44 * a different set of data based on the input
50 * Is this object being embedded in another object. If
51 * so the display routine needs to not do any work. (The
52 * parent object takes care of the display)
56 protected $_embedded = FALSE;
59 * Are we in print mode? if so we need to modify the display
60 * functionality to do a minimal display :)
63 * Should match a CRM_Core_Smarty::PRINT_* constant,
64 * or equal 0 if not in print mode
66 protected $_print = FALSE;
69 * Cache the smarty template for efficiency reasons
71 * @var CRM_Core_Smarty
73 static protected $_template;
76 * Cache the session for efficiency reasons
78 * @var CRM_Core_Session
80 static protected $_session;
83 * What to return to the client if in ajax mode (snippet=json)
87 public $ajaxResponse = [];
90 * Url path used to reach this page
97 * Should crm.livePage.js be added to the page?
100 public $useLivePageJS;
103 * Variables smarty expects to have set.
105 * We ensure these are assigned (value = NULL) when Smarty is instantiated in
106 * order to avoid e-notices / having to use empty or isset in the template layer.
110 public $expectedSmartyVariables = [
113 'hookContentPlacement',
114 // required for footer.tpl
116 // required for info.tpl
121 // required for Summary.tpl (contact summary) but seems
122 // likely to be used more broadly to warrant inclusion here.
129 // Required for footer.tpl,
130 // See ExampleHookTest:testPageOutput.
131 'footer_status_severity',
134 'beginHookFormElements',
140 * @param string $title
145 * @return CRM_Core_Page
147 public function __construct($title = NULL, $mode = NULL) {
148 $this->_name
= CRM_Utils_System
::getClassName($this);
149 $this->_title
= $title;
150 $this->_mode
= $mode;
152 // let the constructor initialize this, should happen only once
153 if (!isset(self
::$_template)) {
154 self
::$_template = CRM_Core_Smarty
::singleton();
155 self
::$_session = CRM_Core_Session
::singleton();
157 // Smarty $_template is a static var which persists between tests, so
158 // if something calls clearTemplateVars(), the static still exists but
159 // our ensured variables get blown away, so we need to set them even if
160 // it's already been initialized.
161 self
::$_template->ensureVariablesAreAssigned($this->expectedSmartyVariables
);
163 // FIXME - why are we messing with 'snippet'? Why not just pass it directly into $this->_print?
164 if (!empty($_REQUEST['snippet'])) {
165 if ($_REQUEST['snippet'] == CRM_Core_Smarty
::PRINT_PDF
) {
166 $this->_print
= CRM_Core_Smarty
::PRINT_PDF
;
168 // FIXME - why does this number not match the constant?
169 elseif ($_REQUEST['snippet'] == 5) {
170 $this->_print
= CRM_Core_Smarty
::PRINT_NOFORM
;
172 // Support 'json' as well as legacy value '6'
173 elseif (in_array($_REQUEST['snippet'], [CRM_Core_Smarty
::PRINT_JSON
, 6])) {
174 $this->_print
= CRM_Core_Smarty
::PRINT_JSON
;
177 $this->_print
= CRM_Core_Smarty
::PRINT_SNIPPET
;
181 // if the request has a reset value, initialize the controller session
182 if (!empty($_REQUEST['reset'])) {
188 * This function takes care of all the things common to all pages.
190 * This typically involves assigning the appropriate smarty variables :)
192 public function run() {
193 if ($this->_embedded
) {
197 self
::$_template->assign('mode', $this->_mode
);
199 $pageTemplateFile = $this->getHookedTemplateFileName();
200 self
::$_template->assign('tplFile', $pageTemplateFile);
202 self
::$_template->addExpectedTabHeaderKeys();
204 // invoke the pagRun hook, CRM-3906
205 CRM_Utils_Hook
::pageRun($this);
208 if (in_array($this->_print
, [
209 CRM_Core_Smarty
::PRINT_SNIPPET
,
210 CRM_Core_Smarty
::PRINT_PDF
,
211 CRM_Core_Smarty
::PRINT_NOFORM
,
212 CRM_Core_Smarty
::PRINT_JSON
,
214 $content = self
::$_template->fetch('CRM/common/snippet.tpl');
217 $content = self
::$_template->fetch('CRM/common/print.tpl');
220 CRM_Utils_System
::appendTPLFile($pageTemplateFile,
222 $this->overrideExtraTemplateFileName()
225 //its time to call the hook.
226 CRM_Utils_Hook
::alterContent($content, 'page', $pageTemplateFile, $this);
228 if ($this->_print
=== CRM_Core_Smarty
::PRINT_PDF
) {
229 CRM_Utils_PDF_Utils
::html2pdf($content, "{$this->_name}.pdf", FALSE);
231 elseif ($this->_print
=== CRM_Core_Smarty
::PRINT_JSON
) {
232 $this->ajaxResponse
['content'] = $content;
233 CRM_Core_Page_AJAX
::returnJsonResponse($this->ajaxResponse
);
238 CRM_Utils_System
::civiExit();
241 $config = CRM_Core_Config
::singleton();
243 // @fixme this is probably the wrong place for this. It is required by jsortable.tpl which is inherited from many page templates.
244 // So we have to add it here to deprecate $config->defaultCurrencySymbol
245 $this->assign('defaultCurrencySymbol', CRM_Core_BAO_Country
::defaultCurrencySymbol());
247 // Intermittent alert to admins
248 CRM_Utils_Check
::singleton()->showPeriodicAlerts();
250 if ($this->useLivePageJS
&& Civi
::settings()->get('ajaxPopupsEnabled')) {
251 CRM_Core_Resources
::singleton()->addScriptFile('civicrm', 'js/crm.livePage.js', 1, 'html-header');
254 $content = self
::$_template->fetch('CRM/common/' . strtolower($config->userFramework
) . '.tpl');
256 // Render page header
257 if (!defined('CIVICRM_UF_HEAD') && $region = CRM_Core_Region
::instance('html-header', FALSE)) {
258 CRM_Utils_System
::addHTMLHead($region->render(''));
260 CRM_Utils_System
::appendTPLFile($pageTemplateFile, $content);
262 //its time to call the hook.
263 CRM_Utils_Hook
::alterContent($content, 'page', $pageTemplateFile, $this);
265 echo CRM_Utils_System
::theme($content, $this->_print
);
269 * Store the variable with the value in the form scope.
271 * @param string|array $name name of the variable or an assoc array of name/value pairs
272 * @param mixed $value
273 * Value of the variable if string.
275 public function set($name, $value = NULL) {
276 self
::$_session->set($name, $value, $this->_name
);
280 * Get the variable from the form scope.
282 * @param string $name name of the variable
286 public function get($name) {
287 return self
::$_session->get($name, $this->_name
);
291 * Assign value to name in template.
294 * @param mixed $value
297 public function assign($var, $value = NULL) {
298 self
::$_template->assign($var, $value);
302 * Assign value to name in template by reference.
305 * @param mixed $value
306 * (reference) value of variable.
308 public function assign_by_ref($var, &$value) {
309 self
::$_template->assign_by_ref($var, $value);
313 * Appends values to template variables.
315 * @param array|string $tpl_var the template variable name(s)
316 * @param mixed $value
317 * The value to append.
320 public function append($tpl_var, $value = NULL, $merge = FALSE) {
321 self
::$_template->append($tpl_var, $value, $merge);
325 * Returns an array containing template variables.
327 * @param string $name
331 public function get_template_vars($name = NULL) {
332 return self
::$_template->get_template_vars($name);
336 * Destroy all the session state of this page.
338 public function reset() {
339 self
::$_session->resetScope($this->_name
);
343 * Use the form name to create the tpl file name.
347 public function getTemplateFileName() {
349 CRM_Utils_System
::getClassName($this),
351 '_' => DIRECTORY_SEPARATOR
,
352 '\\' => DIRECTORY_SEPARATOR
,
358 * A wrapper for getTemplateFileName that includes calling the hook to
359 * prevent us from having to copy & paste the logic of calling the hook
361 public function getHookedTemplateFileName() {
362 $pageTemplateFile = $this->getTemplateFileName();
363 CRM_Utils_Hook
::alterTemplateFile(get_class($this), $this, 'page', $pageTemplateFile);
364 return $pageTemplateFile;
368 * Default extra tpl file basically just replaces .tpl with .extra.tpl
369 * i.e. we dont override
373 public function overrideExtraTemplateFileName() {
378 * Setter for embedded.
380 * @param bool $embedded
382 public function setEmbedded($embedded) {
383 $this->_embedded
= $embedded;
387 * Getter for embedded.
390 * return the embedded value
392 public function getEmbedded() {
393 return $this->_embedded
;
399 * @param int|string $print
400 * Should match a CRM_Core_Smarty::PRINT_* constant,
401 * or equal 0 if not in print mode
405 public function setPrint($print) {
406 $this->_print
= $print;
413 * Value matching a CRM_Core_Smarty::PRINT_* constant,
414 * or 0 if not in print mode
416 public function getPrint() {
417 return $this->_print
;
421 * @return CRM_Core_Smarty
423 public static function &getTemplate() {
424 return self
::$_template;
428 * @param string $name
432 public function getVar($name) {
433 return $this->$name ??
NULL;
437 * @param string $name
440 public function setVar($name, $value) {
441 $this->$name = $value;
445 * Assign metadata about fields to the template.
447 * In order to allow the template to format fields we assign information about them to the template.
449 * At this stage only date field metadata is assigned as that is the only use-case in play and
450 * we don't want to assign a lot of unneeded data.
452 * @param string $entity
453 * The entity being queried.
455 * @throws \CiviCRM_API3_Exception
457 protected function assignFieldMetadataToTemplate($entity) {
458 $fields = civicrm_api3($entity, 'getfields', ['action' => 'get']);
460 foreach ($fields['values'] as $fieldName => $fieldMetaData) {
461 if (isset($fieldMetaData['html']) && CRM_Utils_Array
::value('type', $fieldMetaData['html']) == 'Select Date') {
462 $dateFields[$fieldName] = CRM_Utils_Date
::addDateMetadataToField($fieldMetaData, $fieldMetaData);
465 $this->assign('fields', $dateFields);
469 * Handy helper to produce the standard markup for an icon with alternative
470 * text for a title and screen readers.
472 * See also the smarty block function `icon`
474 * @param string $icon
475 * The class name of the icon to display.
476 * @param string $text
477 * The translated text to display.
478 * @param bool $condition
479 * Whether to display anything at all. This helps simplify code when a
480 * checkmark should appear if something is true.
481 * @param array $attribs
482 * Attributes to set or override on the icon element. Any standard
483 * attribute can be unset by setting the value to an empty string.
486 * The whole bit to drop in.
488 public static function crmIcon($icon, $text = NULL, $condition = TRUE, $attribs = []) {
493 // Add icon classes to any that might exist in $attribs
494 $classes = array_key_exists('class', $attribs) ?
explode(' ', $attribs['class']) : [];
495 $classes[] = 'crm-i';
497 $attribs['class'] = implode(' ', array_unique($classes));
499 $standardAttribs = ['aria-hidden' => 'true'];
500 if ($text === NULL ||
$text === '') {
504 $standardAttribs['title'] = $text;
505 $sr = "<span class=\"sr-only\">$text</span>";
510 // Strip out title if $attribs specifies a blank title
511 $attribs = array_merge($standardAttribs, $attribs);
512 foreach ($attribs as $attrib => $val) {
514 $val = htmlspecialchars($val);
515 $attribString .= " $attrib=\"$val\"";
519 return "<i$attribString></i>$sr";
523 * Add an expected smarty variable to the array.
525 * @param string $elementName
527 public function addExpectedSmartyVariable(string $elementName): void
{
528 $this->expectedSmartyVariables
[] = $elementName;
532 * Add an expected smarty variable to the array.
534 * @param array $elementNames
536 public function addExpectedSmartyVariables(array $elementNames): void
{
537 foreach ($elementNames as $elementName) {
538 // Duplicates don't actually matter....
539 $this->addExpectedSmartyVariable($elementName);