CRM/Core/Form.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This is our base form. It is part of the Form/Controller/StateMachine
  14  * trifecta. Each form is associated with a specific state in the state
  15  * machine. Each form can also operate in various modes
  16  *
  17  * @package CRM
  18  * @copyright CiviCRM LLC https://civicrm.org/licensing
  19  */
  20
  21 require_once 'HTML/QuickForm/Page.php';
  22
  23 /**
  24  * Class CRM_Core_Form
  25  */
  26 class CRM_Core_Form extends HTML_QuickForm_Page {
  27
  28   /**
  29    * The state object that this form belongs to
  30    * @var object
  31    */
  32   protected $_state;
  33
  34   /**
  35    * The name of this form
  36    * @var string
  37    */
  38   protected $_name;
  39
  40   /**
  41    * The title of this form
  42    * @var string
  43    */
  44   protected $_title = NULL;
  45
  46   /**
  47    * The default values for the form.
  48    *
  49    * @var array
  50    */
  51   public $_defaults = [];
  52
  53   /**
  54    * (QUASI-PROTECTED) The options passed into this form
  55    *
  56    * This field should marked `protected` and is not generally
  57    * intended for external callers, but some edge-cases do use it.
  58    *
  59    * @var mixed
  60    */
  61   public $_options = NULL;
  62
  63   /**
  64    * (QUASI-PROTECTED) The mode of operation for this form
  65    *
  66    * This field should marked `protected` and is not generally
  67    * intended for external callers, but some edge-cases do use it.
  68    *
  69    * @var int
  70    */
  71   public $_action;
  72
  73   /**
  74    * Available payment processors.
  75    *
  76    * As part of trying to consolidate various payment pages we store processors here & have functions
  77    * at this level to manage them.
  78    *
  79    * @var array
  80    *   An array of payment processor details with objects loaded in the 'object' field.
  81    */
  82   protected $_paymentProcessors;
  83
  84   /**
  85    * Available payment processors (IDS).
  86    *
  87    * As part of trying to consolidate various payment pages we store processors here & have functions
  88    * at this level to manage them. An alternative would be to have a separate Form that is inherited
  89    * by all forms that allow payment processing.
  90    *
  91    * @var array
  92    *   An array of the IDS available on this form.
  93    */
  94   public $_paymentProcessorIDs;
  95
  96   /**
  97    * Default or selected processor id.
  98    *
  99    * As part of trying to consolidate various payment pages we store processors here & have functions
 100    * at this level to manage them. An alternative would be to have a separate Form that is inherited
 101    * by all forms that allow payment processing.
 102    *
 103    * @var int
 104    */
 105   protected $_paymentProcessorID;
 106
 107   /**
 108    * Is pay later enabled for the form.
 109    *
 110    * As part of trying to consolidate various payment pages we store processors here & have functions
 111    * at this level to manage them. An alternative would be to have a separate Form that is inherited
 112    * by all forms that allow payment processing.
 113    *
 114    * @var int
 115    */
 116   protected $_is_pay_later_enabled;
 117
 118   /**
 119    * The renderer used for this form
 120    *
 121    * @var object
 122    */
 123   protected $_renderer;
 124
 125   /**
 126    * An array to hold a list of datefields on the form
 127    * so that they can be converted to ISO in a consistent manner
 128    *
 129    * @var array
 130    *
 131    * e.g on a form declare $_dateFields = array(
 132    *  'receive_date' => array('default' => 'now'),
 133    *  );
 134    *  then in postProcess call $this->convertDateFieldsToMySQL($formValues)
 135    *  to have the time field re-incorporated into the field & 'now' set if
 136    *  no value has been passed in
 137    */
 138   protected $_dateFields = [];
 139
 140   /**
 141    * Cache the smarty template for efficiency reasons
 142    *
 143    * @var CRM_Core_Smarty
 144    */
 145   static protected $_template;
 146
 147   /**
 148    *  Indicate if this form should warn users of unsaved changes
 149    * @var bool
 150    */
 151   protected $unsavedChangesWarn;
 152
 153   /**
 154    * What to return to the client if in ajax mode (snippet=json)
 155    *
 156    * @var array
 157    */
 158   public $ajaxResponse = [];
 159
 160   /**
 161    * Url path used to reach this page
 162    *
 163    * @var array
 164    */
 165   public $urlPath = [];
 166
 167   /**
 168    * Context of the form being loaded.
 169    *
 170    * 'event' or null
 171    *
 172    * @var string
 173    */
 174   protected $context;
 175
 176   /**
 177    * @var bool
 178    */
 179   public $submitOnce = FALSE;
 180
 181   /**
 182    * @return string
 183    */
 184   public function getContext() {
 185     return $this->context;
 186   }
 187
 188   /**
 189    * Set context variable.
 190    */
 191   public function setContext() {
 192     $this->context = CRM_Utils_Request::retrieve('context', 'Alphanumeric', $this);
 193   }
 194
 195   /**
 196    * @var CRM_Core_Controller
 197    */
 198   public $controller;
 199
 200   /**
 201    * Constants for attributes for various form elements
 202    * attempt to standardize on the number of variations that we
 203    * use of the below form elements
 204    *
 205    * @var const string
 206    */
 207   const ATTR_SPACING = '&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;';
 208
 209   /**
 210    * All checkboxes are defined with a common prefix. This allows us to
 211    * have the same javascript to check / clear all the checkboxes etc
 212    * If u have multiple groups of checkboxes, you will need to give them different
 213    * ids to avoid potential name collision
 214    *
 215    * @var string|int
 216    */
 217   const CB_PREFIX = 'mark_x_', CB_PREFIY = 'mark_y_', CB_PREFIZ = 'mark_z_', CB_PREFIX_LEN = 7;
 218
 219   /**
 220    * @var array
 221    * @internal to keep track of chain-select fields
 222    */
 223   private $_chainSelectFields = [];
 224
 225   /**
 226    * Extra input types we support via the "add" method
 227    * @var array
 228    */
 229   public static $html5Types = [
 230     'number',
 231     'url',
 232     'email',
 233     'color',
 234   ];
 235
 236   /**
 237    * Constructor for the basic form page.
 238    *
 239    * We should not use QuickForm directly. This class provides a lot
 240    * of default convenient functions, rules and buttons
 241    *
 242    * @param object $state
 243    *   State associated with this form.
 244    * @param \const|\enum|int $action The mode the form is operating in (None/Create/View/Update/Delete)
 245    * @param string $method
 246    *   The type of http method used (GET/POST).
 247    * @param string $name
 248    *   The name of the form if different from class name.
 249    *
 250    * @return \CRM_Core_Form
 251    */
 252   public function __construct(
 253     $state = NULL,
 254     $action = CRM_Core_Action::NONE,
 255     $method = 'post',
 256     $name = NULL
 257   ) {
 258
 259     if ($name) {
 260       $this->_name = $name;
 261     }
 262     else {
 263       // CRM-15153 - FIXME this name translates to a DOM id and is not always unique!
 264       $this->_name = CRM_Utils_String::getClassName(CRM_Utils_System::getClassName($this));
 265     }
 266
 267     parent::__construct($this->_name, $method);
 268
 269     $this->_state =& $state;
 270     if ($this->_state) {
 271       $this->_state->setName($this->_name);
 272     }
 273     $this->_action = (int) $action;
 274
 275     $this->registerRules();
 276
 277     // let the constructor initialize this, should happen only once
 278     if (!isset(self::$_template)) {
 279       self::$_template = CRM_Core_Smarty::singleton();
 280     }
 281     // Workaround for CRM-15153 - give each form a reasonably unique css class
 282     $this->addClass(CRM_Utils_System::getClassName($this));
 283
 284     $this->assign('snippet', CRM_Utils_Array::value('snippet', $_GET));
 285     $this->setTranslatedFields();
 286   }
 287
 288   /**
 289    * Set translated fields.
 290    *
 291    * This function is called from the class constructor, allowing us to set
 292    * fields on the class that can't be set as properties due to need for
 293    * translation or other non-input specific handling.
 294    */
 295   protected function setTranslatedFields() {}
 296
 297   /**
 298    * Add one or more css classes to the form.
 299    *
 300    * @param string $className
 301    */
 302   public function addClass($className) {
 303     $classes = $this->getAttribute('class');
 304     $this->setAttribute('class', ($classes ? "$classes " : '') . $className);
 305   }
 306
 307   /**
 308    * Register all the standard rules that most forms potentially use.
 309    */
 310   public function registerRules() {
 311     static $rules = [
 312       'title',
 313       'longTitle',
 314       'variable',
 315       'qfVariable',
 316       'phone',
 317       'integer',
 318       'query',
 319       'url',
 320       'wikiURL',
 321       'domain',
 322       'numberOfDigit',
 323       'date',
 324       'currentDate',
 325       'asciiFile',
 326       'htmlFile',
 327       'utf8File',
 328       'objectExists',
 329       'optionExists',
 330       'postalCode',
 331       'money',
 332       'positiveInteger',
 333       'xssString',
 334       'fileExists',
 335       'settingPath',
 336       'autocomplete',
 337       'validContact',
 338     ];
 339
 340     foreach ($rules as $rule) {
 341       $this->registerRule($rule, 'callback', $rule, 'CRM_Utils_Rule');
 342     }
 343   }
 344
 345   /**
 346    * Simple easy to use wrapper around addElement.
 347    *
 348    * Deal with simple validation rules.
 349    *
 350    * @param string $type
 351    * @param string $name
 352    * @param string $label
 353    * @param array $attributes (options for select elements)
 354    * @param bool $required
 355    * @param array $extra
 356    *   (attributes for select elements).
 357    *   For datepicker elements this is consistent with the data
 358    *   from CRM_Utils_Date::getDatePickerExtra
 359    *
 360    * @return HTML_QuickForm_Element
 361    *   Could be an error object
 362    *
 363    * @throws \CRM_Core_Exception
 364    */
 365   public function &add(
 366     $type, $name, $label = '',
 367     $attributes = NULL, $required = FALSE, $extra = NULL
 368   ) {
 369     if ($type === 'radio') {
 370       CRM_Core_Error::deprecatedFunctionWarning('CRM_Core_Form::addRadio');
 371     }
 372
 373     if ($type !== 'static' && $attributes && !is_array($attributes)) {
 374       // The $attributes param used to allow for strings and would default to an
 375       // empty string.  However, now that the variable is heavily manipulated,
 376       // we should expect it to always be an array.
 377       Civi::log()->warning('Attributes passed to CRM_Core_Form::add() are not an array.', ['civi.tag' => 'deprecated']);
 378     }
 379     // Fudge some extra types that quickform doesn't support
 380     $inputType = $type;
 381     if ($type == 'wysiwyg' || in_array($type, self::$html5Types)) {
 382       $attributes = ($attributes ? $attributes : []) + ['class' => ''];
 383       $attributes['class'] = ltrim($attributes['class'] . " crm-form-$type");
 384       if ($type == 'wysiwyg' && isset($attributes['preset'])) {
 385         $attributes['data-preset'] = $attributes['preset'];
 386         unset($attributes['preset']);
 387       }
 388       $type = $type == 'wysiwyg' ? 'textarea' : 'text';
 389     }
 390     // Like select but accepts rich array data (with nesting, colors, icons, etc) as option list.
 391     if ($inputType == 'select2') {
 392       $type = 'text';
 393       $options = $attributes;
 394       $attributes = ($extra ? $extra : []) + ['class' => ''];
 395       $attributes['class'] = ltrim($attributes['class'] . " crm-select2 crm-form-select2");
 396       $attributes['data-select-params'] = json_encode(['data' => $options, 'multiple' => !empty($attributes['multiple'])]);
 397       unset($attributes['multiple']);
 398       $extra = NULL;
 399     }
 400
 401     // @see https://docs.civicrm.org/dev/en/latest/framework/ui/#date-picker
 402     if ($type === 'datepicker') {
 403       $attributes = $attributes ?: [];
 404       if (!empty($attributes['formatType'])) {
 405         $dateAttributes = CRM_Core_SelectValues::date($attributes['formatType'], NULL, NULL, NULL, 'Input');
 406         if (empty($extra['minDate']) && !empty($dateAttributes['minYear'])) {
 407           $extra['minDate'] = $dateAttributes['minYear'] . '-01-01';
 408         }
 409         if (empty($extra['maxDate']) && !empty($dateAttributes['minYear'])) {
 410           $extra['maxDate'] = $dateAttributes['maxYear'] . '-12-31';
 411         }
 412       }
 413       // Support minDate/maxDate properties
 414       if (isset($extra['minDate'])) {
 415         $extra['minDate'] = date('Y-m-d', strtotime($extra['minDate']));
 416       }
 417       if (isset($extra['maxDate'])) {
 418         $extra['maxDate'] = date('Y-m-d', strtotime($extra['maxDate']));
 419       }
 420
 421       $attributes['data-crm-datepicker'] = json_encode((array) $extra);
 422       if (!empty($attributes['aria-label']) || $label) {
 423         $attributes['aria-label'] = $attributes['aria-label'] ?? $label;
 424       }
 425       $type = "text";
 426     }
 427     if ($type === 'select' && is_array($extra)) {
 428       // Normalize this property
 429       if (!empty($extra['multiple'])) {
 430         $extra['multiple'] = 'multiple';
 431       }
 432       else {
 433         unset($extra['multiple']);
 434       }
 435       unset($extra['size'], $extra['maxlength']);
 436       // Add placeholder option for select
 437       if (isset($extra['placeholder'])) {
 438         if ($extra['placeholder'] === TRUE) {
 439           $extra['placeholder'] = ts('- select %1 -', [1 => $label]);
 440         }
 441         if (($extra['placeholder'] || $extra['placeholder'] === '') && empty($extra['multiple']) && is_array($attributes) && !isset($attributes[''])) {
 442           $attributes = ['' => $extra['placeholder']] + $attributes;
 443         }
 444       }
 445     }
 446     $optionContext = NULL;
 447     if (!empty($extra['option_context'])) {
 448       $optionContext = $extra['option_context'];
 449       unset($extra['option_context']);
 450     }
 451
 452     $element = $this->addElement($type, $name, CRM_Utils_String::purifyHTML($label), $attributes, $extra);
 453     if (HTML_QuickForm::isError($element)) {
 454       CRM_Core_Error::statusBounce(HTML_QuickForm::errorMessage($element));
 455     }
 456
 457     if ($inputType == 'color') {
 458       $this->addRule($name, ts('%1 must contain a color value e.g. #ffffff.', [1 => $label]), 'regex', '/#[0-9a-fA-F]{6}/');
 459     }
 460
 461     if ($required) {
 462       if ($type == 'file') {
 463         $error = $this->addRule($name, ts('%1 is a required field.', [1 => $label]), 'uploadedfile');
 464       }
 465       else {
 466         $error = $this->addRule($name, ts('%1 is a required field.', [1 => $label]), 'required');
 467       }
 468       if (HTML_QuickForm::isError($error)) {
 469         CRM_Core_Error::statusBounce(HTML_QuickForm::errorMessage($element));
 470       }
 471     }
 472
 473     // Add context for the editing of option groups
 474     if ($optionContext) {
 475       $element->setAttribute('data-option-edit-context', json_encode($optionContext));
 476     }
 477
 478     return $element;
 479   }
 480
 481   /**
 482    * Preprocess form.
 483    *
 484    * This is called before buildForm. Any pre-processing that
 485    * needs to be done for buildForm should be done here.
 486    *
 487    * This is a virtual function and should be redefined if needed.
 488    */
 489   public function preProcess() {
 490   }
 491
 492   /**
 493    * Called after the form is validated.
 494    *
 495    * Any processing of form state etc should be done in this function.
 496    * Typically all processing associated with a form should be done
 497    * here and relevant state should be stored in the session
 498    *
 499    * This is a virtual function and should be redefined if needed
 500    */
 501   public function postProcess() {
 502   }
 503
 504   /**
 505    * Main process wrapper.
 506    *
 507    * Implemented so that we can call all the hook functions.
 508    *
 509    * @param bool $allowAjax
 510    *   FIXME: This feels kind of hackish, ideally we would take the json-related code from this function.
 511    *                          and bury it deeper down in the controller
 512    */
 513   public function mainProcess($allowAjax = TRUE) {
 514     $this->postProcess();
 515     $this->postProcessHook();
 516
 517     // Respond with JSON if in AJAX context (also support legacy value '6')
 518     if ($allowAjax && !empty($_REQUEST['snippet']) && in_array($_REQUEST['snippet'], [
 519       CRM_Core_Smarty::PRINT_JSON,
 520       6,
 521     ])) {
 522       $this->ajaxResponse['buttonName'] = str_replace('_qf_' . $this->getAttribute('id') . '_', '', $this->controller->getButtonName());
 523       $this->ajaxResponse['action'] = $this->_action;
 524       if (isset($this->_id) || isset($this->id)) {
 525         $this->ajaxResponse['id'] = $this->id ?? $this->_id;
 526       }
 527       CRM_Core_Page_AJAX::returnJsonResponse($this->ajaxResponse);
 528     }
 529   }
 530
 531   /**
 532    * The postProcess hook is typically called by the framework.
 533    *
 534    * However in a few cases, the form exits or redirects early in which
 535    * case it needs to call this function so other modules can do the needful
 536    * Calling this function directly should be avoided if possible. In general a
 537    * better way is to do setUserContext so the framework does the redirect
 538    */
 539   public function postProcessHook() {
 540     CRM_Utils_Hook::postProcess(get_class($this), $this);
 541   }
 542
 543   /**
 544    * This virtual function is used to build the form.
 545    *
 546    * It replaces the buildForm associated with QuickForm_Page. This allows us to put
 547    * preProcess in front of the actual form building routine
 548    */
 549   public function buildQuickForm() {
 550   }
 551
 552   /**
 553    * This virtual function is used to set the default values of various form elements.
 554    *
 555    * @return array|NULL
 556    *   reference to the array of default values
 557    */
 558   public function setDefaultValues() {
 559     return NULL;
 560   }
 561
 562   /**
 563    * This is a virtual function that adds group and global rules to the form.
 564    *
 565    * Keeping it distinct from the form to keep code small
 566    * and localized in the form building code
 567    */
 568   public function addRules() {
 569   }
 570
 571   /**
 572    * Performs the server side validation.
 573    * @since     1.0
 574    * @return bool
 575    *   true if no error found
 576    * @throws    HTML_QuickForm_Error
 577    */
 578   public function validate() {
 579     $error = parent::validate();
 580
 581     $this->validateChainSelectFields();
 582
 583     $hookErrors = [];
 584
 585     CRM_Utils_Hook::validateForm(
 586       get_class($this),
 587       $this->_submitValues,
 588       $this->_submitFiles,
 589       $this,
 590       $hookErrors
 591     );
 592
 593     if (!empty($hookErrors)) {
 594       $this->_errors += $hookErrors;
 595     }
 596
 597     return (0 == count($this->_errors));
 598   }
 599
 600   /**
 601    * Core function that builds the form.
 602    *
 603    * We redefine this function here and expect all CRM forms to build their form in the function
 604    * buildQuickForm.
 605    */
 606   public function buildForm() {
 607     $this->_formBuilt = TRUE;
 608
 609     $this->preProcess();
 610
 611     CRM_Utils_Hook::preProcess(get_class($this), $this);
 612
 613     $this->assign('translatePermission', CRM_Core_Permission::check('translate CiviCRM'));
 614
 615     if (
 616       $this->controller->_key &&
 617       $this->controller->_generateQFKey
 618     ) {
 619       $this->addElement('hidden', 'qfKey', $this->controller->_key);
 620       $this->assign('qfKey', $this->controller->_key);
 621
 622     }
 623
 624     // _generateQFKey suppresses the qfKey generation on form snippets that
 625     // are part of other forms, hence we use that to avoid adding entryURL
 626     if ($this->controller->_generateQFKey && $this->controller->_entryURL) {
 627       $this->addElement('hidden', 'entryURL', $this->controller->_entryURL);
 628     }
 629
 630     $this->buildQuickForm();
 631
 632     $defaults = $this->setDefaultValues();
 633     unset($defaults['qfKey']);
 634
 635     if (!empty($defaults)) {
 636       $this->setDefaults($defaults);
 637     }
 638
 639     // call the form hook
 640     // also call the hook function so any modules can set their own custom defaults
 641     // the user can do both the form and set default values with this hook
 642     CRM_Utils_Hook::buildForm(get_class($this), $this);
 643
 644     $this->addRules();
 645
 646     //Set html data-attribute to enable warning user of unsaved changes
 647     if ($this->unsavedChangesWarn === TRUE
 648       || (!isset($this->unsavedChangesWarn)
 649         && ($this->_action & CRM_Core_Action::ADD || $this->_action & CRM_Core_Action::UPDATE)
 650       )
 651     ) {
 652       $this->setAttribute('data-warn-changes', 'true');
 653     }
 654
 655     if ($this->submitOnce) {
 656       $this->setAttribute('data-submit-once', 'true');
 657     }
 658   }
 659
 660   /**
 661    * Add default Next / Back buttons.
 662    *
 663    * @param array $params
 664    *   Array of associative arrays in the order in which the buttons should be
 665    *   displayed. The associate array has 3 fields: 'type', 'name' and 'isDefault'
 666    *   The base form class will define a bunch of static arrays for commonly used
 667    *   formats.
 668    */
 669   public function addButtons($params) {
 670     $prevnext = $spacing = [];
 671     foreach ($params as $button) {
 672       if (!empty($button['submitOnce'])) {
 673         $this->submitOnce = TRUE;
 674       }
 675
 676       $attrs = ['class' => 'crm-form-submit'] + (array) CRM_Utils_Array::value('js', $button);
 677
 678       // A lot of forms use the hacky method of looking at
 679       // `$params['button name']` (dating back to them being inputs with a
 680       // "value" of the button label) rather than looking at
 681       // `$this->controller->getButtonName()`. It makes sense to give buttons a
 682       // value by default as a precaution.
 683       $attrs['value'] = 1;
 684
 685       if (!empty($button['class'])) {
 686         $attrs['class'] .= ' ' . $button['class'];
 687       }
 688
 689       if (!empty($button['isDefault'])) {
 690         $attrs['class'] .= ' default';
 691       }
 692
 693       if (in_array($button['type'], ['upload', 'next', 'submit', 'done', 'process', 'refresh'])) {
 694         $attrs['class'] .= ' validate';
 695         $defaultIcon = 'fa-check';
 696       }
 697       else {
 698         $attrs['class'] .= ' cancel';
 699         $defaultIcon = $button['type'] == 'back' ? 'fa-chevron-left' : 'fa-times';
 700       }
 701
 702       if ($button['type'] === 'reset') {
 703         $attrs['type'] = 'reset';
 704         $prevnext[] = $this->createElement('xbutton', 'reset', $button['name'], $attrs);
 705       }
 706       else {
 707         if (!empty($button['subName'])) {
 708           if ($button['subName'] == 'new') {
 709             $defaultIcon = 'fa-plus-circle';
 710           }
 711           if ($button['subName'] == 'done') {
 712             $defaultIcon = 'fa-check-circle';
 713           }
 714           if ($button['subName'] == 'next') {
 715             $defaultIcon = 'fa-chevron-right';
 716           }
 717         }
 718
 719         if (in_array($button['type'], ['next', 'upload', 'done']) && $button['name'] === ts('Save')) {
 720           $attrs['accesskey'] = 'S';
 721         }
 722         $buttonContents = CRM_Core_Page::crmIcon($button['icon'] ?? $defaultIcon) . ' ' . $button['name'];
 723         $buttonName = $this->getButtonName($button['type'], CRM_Utils_Array::value('subName', $button));
 724         $attrs['class'] .= " crm-button crm-button-type-{$button['type']} crm-button{$buttonName}";
 725         $attrs['type'] = 'submit';
 726         $prevnext[] = $this->createElement('xbutton', $buttonName, $buttonContents, $attrs);
 727       }
 728       if (!empty($button['isDefault'])) {
 729         $this->setDefaultAction($button['type']);
 730       }
 731
 732       // if button type is upload, set the enctype
 733       if ($button['type'] == 'upload') {
 734         $this->updateAttributes(['enctype' => 'multipart/form-data']);
 735         $this->setMaxFileSize();
 736       }
 737
 738       // hack - addGroup uses an array to express variable spacing, read from the last element
 739       $spacing[] = CRM_Utils_Array::value('spacing', $button, self::ATTR_SPACING);
 740     }
 741     $this->addGroup($prevnext, 'buttons', '', $spacing, FALSE);
 742   }
 743
 744   /**
 745    * Getter function for Name.
 746    *
 747    * @return string
 748    */
 749   public function getName() {
 750     return $this->_name;
 751   }
 752
 753   /**
 754    * Getter function for State.
 755    *
 756    * @return object
 757    */
 758   public function &getState() {
 759     return $this->_state;
 760   }
 761
 762   /**
 763    * Getter function for StateType.
 764    *
 765    * @return int
 766    */
 767   public function getStateType() {
 768     return $this->_state->getType();
 769   }
 770
 771   /**
 772    * Getter function for title.
 773    *
 774    * Should be over-ridden by derived class.
 775    *
 776    * @return string
 777    */
 778   public function getTitle() {
 779     return $this->_title ? $this->_title : ts('ERROR: Title is not Set');
 780   }
 781
 782   /**
 783    * Setter function for title.
 784    *
 785    * @param string $title
 786    *   The title of the form.
 787    */
 788   public function setTitle($title) {
 789     $this->_title = $title;
 790     CRM_Utils_System::setTitle($title);
 791   }
 792
 793   /**
 794    * Assign billing type id to bltID.
 795    *
 796    * @throws CRM_Core_Exception
 797    */
 798   public function assignBillingType() {
 799     $this->_bltID = CRM_Core_BAO_LocationType::getBilling();
 800     $this->set('bltID', $this->_bltID);
 801     $this->assign('bltID', $this->_bltID);
 802   }
 803
 804   /**
 805    * @return int
 806    */
 807   public function getPaymentProcessorID() {
 808     return $this->_paymentProcessorID;
 809   }
 810
 811   /**
 812    * This if a front end form function for setting the payment processor.
 813    *
 814    * It would be good to sync it with the back-end function on abstractEditPayment & use one everywhere.
 815    *
 816    * @param bool $isPayLaterEnabled
 817    *
 818    * @throws \CRM_Core_Exception
 819    */
 820   protected function assignPaymentProcessor($isPayLaterEnabled) {
 821     $this->_paymentProcessors = CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors([ucfirst($this->_mode) . 'Mode'], $this->_paymentProcessorIDs);
 822     if ($isPayLaterEnabled) {
 823       $this->_paymentProcessors[0] = CRM_Financial_BAO_PaymentProcessor::getPayment(0);
 824     }
 825
 826     if (!empty($this->_paymentProcessors)) {
 827       foreach ($this->_paymentProcessors as $paymentProcessorID => $paymentProcessorDetail) {
 828         if (empty($this->_paymentProcessor) && $paymentProcessorDetail['is_default'] == 1 || (count($this->_paymentProcessors) == 1)
 829         ) {
 830           $this->_paymentProcessor = $paymentProcessorDetail;
 831           $this->assign('paymentProcessor', $this->_paymentProcessor);
 832           // Setting this is a bit of a legacy overhang.
 833           $this->_paymentObject = $paymentProcessorDetail['object'];
 834         }
 835       }
 836       // It's not clear why we set this on the form.
 837       $this->set('paymentProcessors', $this->_paymentProcessors);
 838     }
 839     else {
 840       throw new CRM_Core_Exception(ts('A payment processor configured for this page might be disabled (contact the site administrator for assistance).'));
 841     }
 842   }
 843
 844   /**
 845    * Assign an array of variables to the form/tpl
 846    *
 847    * @param array $values Array of [key => value] to assign to the form
 848    * @param array $keys Array of keys to assign from the values array
 849    */
 850   public function assignVariables($values, $keys) {
 851     foreach ($keys as $key) {
 852       $this->assign($key, $values[$key] ?? NULL);
 853     }
 854   }
 855
 856   /**
 857    * Format the fields in $this->_params for the payment processor.
 858    *
 859    * In order to pass fields to the payment processor in a consistent way we add some renamed
 860    * parameters.
 861    *
 862    * @param array $fields
 863    *
 864    * @return array
 865    */
 866   protected function formatParamsForPaymentProcessor($fields) {
 867     $this->_params = $this->prepareParamsForPaymentProcessor($this->_params);
 868     $fields = array_merge($fields, ['first_name' => 1, 'middle_name' => 1, 'last_name' => 1]);
 869     return $fields;
 870   }
 871
 872   /**
 873    * Format the fields in $params for the payment processor.
 874    *
 875    * In order to pass fields to the payment processor in a consistent way we add some renamed
 876    * parameters.
 877    *
 878    * @param array $params Payment processor params
 879    *
 880    * @return array $params
 881    */
 882   protected function prepareParamsForPaymentProcessor($params) {
 883     // also add location name to the array
 884     $params["address_name-{$this->_bltID}"] = CRM_Utils_Array::value('billing_first_name', $params) . ' ' . CRM_Utils_Array::value('billing_middle_name', $params) . ' ' . CRM_Utils_Array::value('billing_last_name', $params);
 885     $params["address_name-{$this->_bltID}"] = trim($params["address_name-{$this->_bltID}"]);
 886     // Add additional parameters that the payment processors are used to receiving.
 887     if (!empty($params["billing_state_province_id-{$this->_bltID}"])) {
 888       $params['state_province'] = $params["state_province-{$this->_bltID}"] = $params["billing_state_province-{$this->_bltID}"] = CRM_Core_PseudoConstant::stateProvinceAbbreviation($params["billing_state_province_id-{$this->_bltID}"]);
 889     }
 890     if (!empty($params["billing_country_id-{$this->_bltID}"])) {
 891       $params['country'] = $params["country-{$this->_bltID}"] = $params["billing_country-{$this->_bltID}"] = CRM_Core_PseudoConstant::countryIsoCode($params["billing_country_id-{$this->_bltID}"]);
 892     }
 893
 894     list($hasAddressField, $addressParams) = CRM_Contribute_BAO_Contribution::getPaymentProcessorReadyAddressParams($params, $this->_bltID);
 895     if ($hasAddressField) {
 896       $params = array_merge($params, $addressParams);
 897     }
 898
 899     // How does this relate to similar code in CRM_Contact_BAO_Contact::addBillingNameFieldsIfOtherwiseNotSet()?
 900     $nameFields = ['first_name', 'middle_name', 'last_name'];
 901     foreach ($nameFields as $name) {
 902       if (array_key_exists("billing_$name", $params)) {
 903         $params[$name] = $params["billing_{$name}"];
 904         $params['preserveDBName'] = TRUE;
 905       }
 906     }
 907
 908     // For legacy reasons we set these creditcard expiry fields if present
 909     CRM_Contribute_Form_AbstractEditPayment::formatCreditCardDetails($params);
 910
 911     // Assign IP address parameter
 912     $params['ip_address'] = CRM_Utils_System::ipAddress();
 913
 914     return $params;
 915   }
 916
 917   /**
 918    * Handle Payment Processor switching for contribution and event registration forms.
 919    *
 920    * This function is shared between contribution & event forms & this is their common class.
 921    *
 922    * However, this should be seen as an in-progress refactor, the end goal being to also align the
 923    * backoffice forms that action payments.
 924    *
 925    * This function overlaps assignPaymentProcessor, in a bad way.
 926    */
 927   protected function preProcessPaymentOptions() {
 928     $this->_paymentProcessorID = NULL;
 929     if ($this->_paymentProcessors) {
 930       if (!empty($this->_submitValues)) {
 931         $this->_paymentProcessorID = $this->_submitValues['payment_processor_id'] ?? NULL;
 932         $this->_paymentProcessor = $this->_paymentProcessors[$this->_paymentProcessorID] ?? NULL;
 933         $this->set('type', $this->_paymentProcessorID);
 934         $this->set('mode', $this->_mode);
 935         $this->set('paymentProcessor', $this->_paymentProcessor);
 936       }
 937       // Set default payment processor
 938       else {
 939         foreach ($this->_paymentProcessors as $values) {
 940           if (!empty($values['is_default']) || count($this->_paymentProcessors) == 1) {
 941             $this->_paymentProcessorID = $values['id'];
 942             break;
 943           }
 944         }
 945       }
 946       if ($this->_paymentProcessorID
 947         || (isset($this->_submitValues['payment_processor_id']) && $this->_submitValues['payment_processor_id'] == 0)
 948       ) {
 949         CRM_Core_Payment_ProcessorForm::preProcess($this);
 950       }
 951       else {
 952         $this->_paymentProcessor = [];
 953       }
 954     }
 955
 956     // We save the fact that the profile 'billing' is required on the payment form.
 957     // Currently pay-later is the only 'processor' that takes notice of this - but ideally
 958     // 1) it would be possible to select the minimum_billing_profile_id for the contribution form
 959     // 2) that profile_id would be set on the payment processor
 960     // 3) the payment processor would return a billing form that combines these user-configured
 961     // minimums with the payment processor minimums. This would lead to fields like 'postal_code'
 962     // only being on the form if either the admin has configured it as wanted or the processor
 963     // requires it.
 964     $this->assign('billing_profile_id', (!empty($this->_values['is_billing_required']) ? 'billing' : ''));
 965   }
 966
 967   /**
 968    * Handle pre approval for processors.
 969    *
 970    * This fits with the flow where a pre-approval is done and then confirmed in the next stage when confirm is hit.
 971    *
 972    * This function is shared between contribution & event forms & this is their common class.
 973    *
 974    * However, this should be seen as an in-progress refactor, the end goal being to also align the
 975    * backoffice forms that action payments.
 976    *
 977    * @param array $params
 978    */
 979   protected function handlePreApproval(&$params) {
 980     try {
 981       $payment = Civi\Payment\System::singleton()->getByProcessor($this->_paymentProcessor);
 982       $params['component'] = $params['component'] ?? 'contribute';
 983       $result = $payment->doPreApproval($params);
 984       if (empty($result)) {
 985         // This could happen, for example, when paypal looks at the button value & decides it is not paypal express.
 986         return;
 987       }
 988     }
 989     catch (\Civi\Payment\Exception\PaymentProcessorException $e) {
 990       CRM_Core_Error::statusBounce(ts('Payment approval failed with message :') . $e->getMessage(), $payment->getCancelUrl($params['qfKey'], CRM_Utils_Array::value('participant_id', $params)));
 991     }
 992
 993     $this->set('pre_approval_parameters', $result['pre_approval_parameters']);
 994     if (!empty($result['redirect_url'])) {
 995       CRM_Utils_System::redirect($result['redirect_url']);
 996     }
 997   }
 998
 999   /**
1000    * Setter function for options.
1001    *
1002    * @param mixed $options
1003    */
1004   public function setOptions($options) {
1005     $this->_options = $options;
1006   }
1007
1008   /**
1009    * Render form and return contents.
1010    *
1011    * @return string
1012    */
1013   public function toSmarty() {
1014     $this->preProcessChainSelectFields();
1015     $renderer = $this->getRenderer();
1016     $this->accept($renderer);
1017     $content = $renderer->toArray();
1018     $content['formName'] = $this->getName();
1019     // CRM-15153
1020     $content['formClass'] = CRM_Utils_System::getClassName($this);
1021     return $content;
1022   }
1023
1024   /**
1025    * Getter function for renderer.
1026    *
1027    * If renderer is not set create one and initialize it.
1028    *
1029    * @return object
1030    */
1031   public function &getRenderer() {
1032     if (!isset($this->_renderer)) {
1033       $this->_renderer = CRM_Core_Form_Renderer::singleton();
1034     }
1035     return $this->_renderer;
1036   }
1037
1038   /**
1039    * Use the form name to create the tpl file name.
1040    *
1041    * @return string
1042    */
1043   public function getTemplateFileName() {
1044     $ext = CRM_Extension_System::singleton()->getMapper();
1045     if ($ext->isExtensionClass(CRM_Utils_System::getClassName($this))) {
1046       $filename = $ext->getTemplateName(CRM_Utils_System::getClassName($this));
1047       $tplname = $ext->getTemplatePath(CRM_Utils_System::getClassName($this)) . DIRECTORY_SEPARATOR . $filename;
1048     }
1049     else {
1050       $tplname = strtr(
1051         CRM_Utils_System::getClassName($this),
1052         [
1053           '_' => DIRECTORY_SEPARATOR,
1054           '\\' => DIRECTORY_SEPARATOR,
1055         ]
1056       ) . '.tpl';
1057     }
1058     return $tplname;
1059   }
1060
1061   /**
1062    * A wrapper for getTemplateFileName.
1063    *
1064    * This includes calling the hook to prevent us from having to copy & paste the logic of calling the hook.
1065    */
1066   public function getHookedTemplateFileName() {
1067     $pageTemplateFile = $this->getTemplateFileName();
1068     CRM_Utils_Hook::alterTemplateFile(get_class($this), $this, 'page', $pageTemplateFile);
1069     return $pageTemplateFile;
1070   }
1071
1072   /**
1073    * Default extra tpl file basically just replaces .tpl with .extra.tpl.
1074    *
1075    * i.e. we do not override.
1076    *
1077    * @return string
1078    */
1079   public function overrideExtraTemplateFileName() {
1080     return NULL;
1081   }
1082
1083   /**
1084    * Error reporting mechanism.
1085    *
1086    * @param string $message
1087    *   Error Message.
1088    * @param int $code
1089    *   Error Code.
1090    * @param CRM_Core_DAO $dao
1091    *   A data access object on which we perform a rollback if non - empty.
1092    */
1093   public function error($message, $code = NULL, $dao = NULL) {
1094     if ($dao) {
1095       $dao->query('ROLLBACK');
1096     }
1097
1098     $error = CRM_Core_Error::singleton();
1099
1100     $error->push($code, $message);
1101   }
1102
1103   /**
1104    * Store the variable with the value in the form scope.
1105    *
1106    * @param string $name
1107    *   Name of the variable.
1108    * @param mixed $value
1109    *   Value of the variable.
1110    */
1111   public function set($name, $value) {
1112     $this->controller->set($name, $value);
1113   }
1114
1115   /**
1116    * Get the variable from the form scope.
1117    *
1118    * @param string $name
1119    *   Name of the variable
1120    *
1121    * @return mixed
1122    */
1123   public function get($name) {
1124     return $this->controller->get($name);
1125   }
1126
1127   /**
1128    * Getter for action.
1129    *
1130    * @return int
1131    */
1132   public function getAction() {
1133     return $this->_action;
1134   }
1135
1136   /**
1137    * Setter for action.
1138    *
1139    * @param int $action
1140    *   The mode we want to set the form.
1141    */
1142   public function setAction($action) {
1143     $this->_action = $action;
1144   }
1145
1146   /**
1147    * Assign value to name in template.
1148    *
1149    * @param string $var
1150    *   Name of variable.
1151    * @param mixed $value
1152    *   Value of variable.
1153    */
1154   public function assign($var, $value = NULL) {
1155     self::$_template->assign($var, $value);
1156   }
1157
1158   /**
1159    * Assign value to name in template by reference.
1160    *
1161    * @param string $var
1162    *   Name of variable.
1163    * @param mixed $value
1164    *   Value of variable.
1165    */
1166   public function assign_by_ref($var, &$value) {
1167     self::$_template->assign_by_ref($var, $value);
1168   }
1169
1170   /**
1171    * Appends values to template variables.
1172    *
1173    * @param array|string $tpl_var the template variable name(s)
1174    * @param mixed $value
1175    *   The value to append.
1176    * @param bool $merge
1177    */
1178   public function append($tpl_var, $value = NULL, $merge = FALSE) {
1179     self::$_template->append($tpl_var, $value, $merge);
1180   }
1181
1182   /**
1183    * Returns an array containing template variables.
1184    *
1185    * @param string $name
1186    *
1187    * @return array
1188    */
1189   public function get_template_vars($name = NULL) {
1190     return self::$_template->get_template_vars($name);
1191   }
1192
1193   /**
1194    * @param string $name
1195    * @param $title
1196    * @param $values
1197    * @param array $attributes
1198    * @param null $separator
1199    * @param bool $required
1200    * @param array $optionAttributes - Option specific attributes
1201    *
1202    * @return HTML_QuickForm_group
1203    */
1204   public function &addRadio($name, $title, $values, $attributes = [], $separator = NULL, $required = FALSE, $optionAttributes = []) {
1205     $options = [];
1206     $attributes = $attributes ? $attributes : [];
1207     $allowClear = !empty($attributes['allowClear']);
1208     unset($attributes['allowClear']);
1209     $attributes['id_suffix'] = $name;
1210     foreach ($values as $key => $var) {
1211       $optAttributes = $attributes;
1212       if (!empty($optionAttributes[$key])) {
1213         foreach ($optionAttributes[$key] as $optAttr => $optVal) {
1214           $optAttributes[$optAttr] = ltrim(($optAttributes[$optAttr] ?? '') . ' ' . $optVal);
1215         }
1216       }
1217       // We use a class here to avoid html5 issues with collapsed cutsomfield sets.
1218       $optAttributes['class'] = $optAttributes['class'] ?? '';
1219       if ($required) {
1220         $optAttributes['class'] .= ' required';
1221       }
1222       $element = $this->createElement('radio', NULL, NULL, $var, $key, $optAttributes);
1223       $options[] = $element;
1224     }
1225     $group = $this->addGroup($options, $name, $title, $separator);
1226
1227     $optionEditKey = 'data-option-edit-path';
1228     if (!empty($attributes[$optionEditKey])) {
1229       $group->setAttribute($optionEditKey, $attributes[$optionEditKey]);
1230     }
1231
1232     if ($required) {
1233       $this->addRule($name, ts('%1 is a required field.', [1 => $title]), 'required');
1234     }
1235     if ($allowClear) {
1236       $group->setAttribute('allowClear', TRUE);
1237     }
1238     return $group;
1239   }
1240
1241   /**
1242    * @param int $id
1243    * @param $title
1244    * @param bool $allowClear
1245    * @param null $required
1246    * @param array $attributes
1247    */
1248   public function addYesNo($id, $title, $allowClear = FALSE, $required = NULL, $attributes = []) {
1249     $attributes += ['id_suffix' => $id];
1250     $choice = [];
1251     $choice[] = $this->createElement('radio', NULL, '11', ts('Yes'), '1', $attributes);
1252     $choice[] = $this->createElement('radio', NULL, '11', ts('No'), '0', $attributes);
1253
1254     $group = $this->addGroup($choice, $id, $title);
1255     if ($allowClear) {
1256       $group->setAttribute('allowClear', TRUE);
1257     }
1258     if ($required) {
1259       $this->addRule($id, ts('%1 is a required field.', [1 => $title]), 'required');
1260     }
1261   }
1262
1263   /**
1264    * @param int $id
1265    * @param $title
1266    * @param $values
1267    * @param null $other
1268    * @param null $attributes
1269    * @param null $required
1270    * @param null $javascriptMethod
1271    * @param string $separator
1272    * @param bool $flipValues
1273    */
1274   public function addCheckBox(
1275     $id, $title, $values, $other = NULL,
1276     $attributes = NULL, $required = NULL,
1277     $javascriptMethod = NULL,
1278     $separator = '<br />', $flipValues = FALSE
1279   ) {
1280     $options = [];
1281
1282     if ($javascriptMethod) {
1283       foreach ($values as $key => $var) {
1284         if (!$flipValues) {
1285           $options[] = $this->createElement('checkbox', $var, NULL, $key, $javascriptMethod, $attributes);
1286         }
1287         else {
1288           $options[] = $this->createElement('checkbox', $key, NULL, $var, $javascriptMethod, $attributes);
1289         }
1290       }
1291     }
1292     else {
1293       foreach ($values as $key => $var) {
1294         if (!$flipValues) {
1295           $options[] = $this->createElement('checkbox', $var, NULL, $key, $attributes);
1296         }
1297         else {
1298           $options[] = $this->createElement('checkbox', $key, NULL, $var, $attributes);
1299         }
1300       }
1301     }
1302
1303     $group = $this->addGroup($options, $id, $title, $separator);
1304     $optionEditKey = 'data-option-edit-path';
1305     if (!empty($attributes[$optionEditKey])) {
1306       $group->setAttribute($optionEditKey, $attributes[$optionEditKey]);
1307     }
1308
1309     if ($other) {
1310       $this->addElement('text', $id . '_other', ts('Other'), $attributes[$id . '_other']);
1311     }
1312
1313     if ($required) {
1314       $this->addRule($id,
1315         ts('%1 is a required field.', [1 => $title]),
1316         'required'
1317       );
1318     }
1319   }
1320
1321   public function resetValues() {
1322     $data = $this->controller->container();
1323     $data['values'][$this->_name] = [];
1324   }
1325
1326   /**
1327    * Simple shell that derived classes can call to add buttons to
1328    * the form with a customized title for the main Submit
1329    *
1330    * @param string $title
1331    *   Title of the main button.
1332    * @param string $nextType
1333    *   Button type for the form after processing.
1334    * @param string $backType
1335    * @param bool|string $submitOnce
1336    */
1337   public function addDefaultButtons($title, $nextType = 'next', $backType = 'back', $submitOnce = FALSE) {
1338     $buttons = [];
1339     if ($backType != NULL) {
1340       $buttons[] = [
1341         'type' => $backType,
1342         'name' => ts('Previous'),
1343       ];
1344     }
1345     if ($nextType != NULL) {
1346       $nextButton = [
1347         'type' => $nextType,
1348         'name' => $title,
1349         'isDefault' => TRUE,
1350       ];
1351       if ($submitOnce) {
1352         $this->submitOnce = TRUE;
1353       }
1354       $buttons[] = $nextButton;
1355     }
1356     $this->addButtons($buttons);
1357   }
1358
1359   /**
1360    * @param string $name
1361    * @param string $from
1362    * @param string $to
1363    * @param string $label
1364    * @param string $dateFormat
1365    * @param bool $required
1366    * @param bool $displayTime
1367    */
1368   public function addDateRange($name, $from = '_from', $to = '_to', $label = 'From:', $dateFormat = 'searchDate', $required = FALSE, $displayTime = FALSE) {
1369     CRM_Core_Error::deprecatedFunctionWarning('Use CRM_Core_Form::addDatePickerRange insted');
1370     if ($displayTime) {
1371       $this->addDateTime($name . $from, $label, $required, ['formatType' => $dateFormat]);
1372       $this->addDateTime($name . $to, ts('To:'), $required, ['formatType' => $dateFormat]);
1373     }
1374     else {
1375       $this->addDate($name . $from, $label, $required, ['formatType' => $dateFormat]);
1376       $this->addDate($name . $to, ts('To:'), $required, ['formatType' => $dateFormat]);
1377     }
1378   }
1379
1380   /**
1381    * Add a search for a range using date picker fields.
1382    *
1383    * @param string $fieldName
1384    * @param string $label
1385    * @param bool $isDateTime
1386    *   Is this a date-time field (not just date).
1387    * @param bool $required
1388    * @param string $fromLabel
1389    * @param string $toLabel
1390    * @param array $additionalOptions
1391    * @param string $to string to append to the to field.
1392    * @param string $from string to append to the from field.
1393    */
1394   public function addDatePickerRange($fieldName, $label, $isDateTime = FALSE, $required = FALSE, $fromLabel = 'From', $toLabel = 'To', $additionalOptions = [],
1395     $to = '_high', $from = '_low') {
1396
1397     $options = [
1398       '' => ts('- any -'),
1399       0 => ts('Choose Date Range'),
1400     ] + CRM_Core_OptionGroup::values('relative_date_filters');
1401
1402     if ($additionalOptions) {
1403       foreach ($additionalOptions as $key => $optionLabel) {
1404         $options[$key] = $optionLabel;
1405       }
1406     }
1407
1408     $this->add('select',
1409       "{$fieldName}_relative",
1410       $label,
1411       $options,
1412       $required,
1413       ['class' => 'crm-select2']
1414     );
1415     $attributes = ['formatType' => 'searchDate'];
1416     $extra = ['time' => $isDateTime];
1417     $this->add('datepicker', $fieldName . $from, ts($fromLabel), $attributes, $required, $extra);
1418     $this->add('datepicker', $fieldName . $to, ts($toLabel), $attributes, $required, $extra);
1419   }
1420
1421   /**
1422    * Based on form action, return a string representing the api action.
1423    * Used by addField method.
1424    *
1425    * Return string
1426    */
1427   protected function getApiAction() {
1428     $action = $this->getAction();
1429     if ($action & (CRM_Core_Action::UPDATE + CRM_Core_Action::ADD)) {
1430       return 'create';
1431     }
1432     if ($action & (CRM_Core_Action::VIEW + CRM_Core_Action::BROWSE + CRM_Core_Action::BASIC + CRM_Core_Action::ADVANCED + CRM_Core_Action::PREVIEW)) {
1433       return 'get';
1434     }
1435     if ($action & (CRM_Core_Action::DELETE)) {
1436       return 'delete';
1437     }
1438     // If you get this exception try adding more cases above.
1439     throw new Exception("Cannot determine api action for " . get_class($this) . '.' . 'CRM_Core_Action "' . CRM_Core_Action::description($action) . '" not recognized.');
1440   }
1441
1442   /**
1443    * Classes extending CRM_Core_Form should implement this method.
1444    * @throws Exception
1445    */
1446   public function getDefaultEntity() {
1447     throw new Exception("Cannot determine default entity. " . get_class($this) . " should implement getDefaultEntity().");
1448   }
1449
1450   /**
1451    * Classes extending CRM_Core_Form should implement this method.
1452    *
1453    * TODO: Merge with CRM_Core_DAO::buildOptionsContext($context) and add validation.
1454    * @throws Exception
1455    */
1456   public function getDefaultContext() {
1457     throw new Exception("Cannot determine default context. " . get_class($this) . " should implement getDefaultContext().");
1458   }
1459
1460   /**
1461    * Adds a select based on field metadata.
1462    * TODO: This could be even more generic and widget type (select in this case) could also be read from metadata
1463    * Perhaps a method like $form->bind($name) which would look up all metadata for named field
1464    * @param $name
1465    *   Field name to go on the form.
1466    * @param array $props
1467    *   Mix of html attributes and special properties, namely.
1468    *   - entity (api entity name, can usually be inferred automatically from the form class)
1469    *   - field (field name - only needed if different from name used on the form)
1470    *   - option_url - path to edit this option list - usually retrieved automatically - set to NULL to disable link
1471    *   - placeholder - set to NULL to disable
1472    *   - multiple - bool
1473    *   - context - @see CRM_Core_DAO::buildOptionsContext
1474    * @param bool $required
1475    * @throws CRM_Core_Exception
1476    * @return HTML_QuickForm_Element
1477    */
1478   public function addSelect($name, $props = [], $required = FALSE) {
1479     if (!isset($props['entity'])) {
1480       $props['entity'] = $this->getDefaultEntity();
1481     }
1482     if (!isset($props['field'])) {
1483       $props['field'] = strrpos($name, '[') ? rtrim(substr($name, 1 + strrpos($name, '[')), ']') : $name;
1484     }
1485     if (!isset($props['context'])) {
1486       try {
1487         $props['context'] = $this->getDefaultContext();
1488       }
1489       // This is not a required param, so we'll ignore if this doesn't exist.
1490       catch (Exception $e) {
1491       }
1492     }
1493     // Fetch options from the api unless passed explicitly
1494     if (isset($props['options'])) {
1495       $options = $props['options'];
1496     }
1497     else {
1498       $info = civicrm_api3($props['entity'], 'getoptions', $props);
1499       $options = $info['values'];
1500     }
1501     if (!array_key_exists('placeholder', $props) && $placeholder = self::selectOrAnyPlaceholder($props, $required)) {
1502       $props['placeholder'] = $placeholder;
1503     }
1504     // Handle custom field
1505     if (strpos($name, 'custom_') === 0 && is_numeric($name[7])) {
1506       list(, $id) = explode('_', $name);
1507       $label = $props['label'] ?? CRM_Core_DAO::getFieldValue('CRM_Core_DAO_CustomField', 'label', $id);
1508       $gid = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_CustomField', 'option_group_id', $id);
1509       if (CRM_Utils_Array::value('context', $props) != 'search') {
1510         $props['data-option-edit-path'] = array_key_exists('option_url', $props) ? $props['option_url'] : 'civicrm/admin/options/' . CRM_Core_DAO::getFieldValue('CRM_Core_DAO_OptionGroup', $gid);
1511       }
1512     }
1513     // Core field
1514     else {
1515       $info = civicrm_api3($props['entity'], 'getfields');
1516       foreach ($info['values'] as $uniqueName => $fieldSpec) {
1517         if (
1518           $uniqueName === $props['field'] ||
1519           CRM_Utils_Array::value('name', $fieldSpec) === $props['field'] ||
1520           in_array($props['field'], CRM_Utils_Array::value('api.aliases', $fieldSpec, []))
1521         ) {
1522           break;
1523         }
1524       }
1525       $label = $props['label'] ?? $fieldSpec['title'];
1526       if (CRM_Utils_Array::value('context', $props) != 'search') {
1527         $props['data-option-edit-path'] = array_key_exists('option_url', $props) ? $props['option_url'] : CRM_Core_PseudoConstant::getOptionEditUrl($fieldSpec);
1528       }
1529     }
1530     $props['class'] = (isset($props['class']) ? $props['class'] . ' ' : '') . "crm-select2";
1531     $props['data-api-entity'] = $props['entity'];
1532     $props['data-api-field'] = $props['field'];
1533     CRM_Utils_Array::remove($props, 'label', 'entity', 'field', 'option_url', 'options', 'context');
1534     return $this->add('select', $name, $label, $options, $required, $props);
1535   }
1536
1537   /**
1538    * Handles a repeated bit supplying a placeholder for entity selection
1539    *
1540    * @param string $props
1541    *   The field properties, including the entity and context.
1542    * @param bool $required
1543    *   If the field is required.
1544    * @return string
1545    *   The placeholder text.
1546    */
1547   private static function selectOrAnyPlaceholder($props, $required) {
1548     if (empty($props['entity'])) {
1549       return NULL;
1550     }
1551     $daoToClass = CRM_Core_DAO_AllCoreTables::daoToClass();
1552     if (array_key_exists($props['entity'], $daoToClass)) {
1553       $daoClass = $daoToClass[$props['entity']];
1554       $tsPlaceholder = $daoClass::getEntityTitle();
1555     }
1556     else {
1557       $tsPlaceholder = ts('option');
1558     }
1559     if (($props['context'] ?? '') == 'search' && !$required) {
1560       return ts('- any %1 -', [1 => $tsPlaceholder]);
1561     }
1562     return ts('- select %1 -', [1 => $tsPlaceholder]);
1563   }
1564
1565   /**
1566    * Adds a field based on metadata.
1567    *
1568    * @param $name
1569    *   Field name to go on the form.
1570    * @param array $props
1571    *   Mix of html attributes and special properties, namely.
1572    *   - entity (api entity name, can usually be inferred automatically from the form class)
1573    *   - name (field name - only needed if different from name used on the form)
1574    *   - option_url - path to edit this option list - usually retrieved automatically - set to NULL to disable link
1575    *   - placeholder - set to NULL to disable
1576    *   - multiple - bool
1577    *   - context - @see CRM_Core_DAO::buildOptionsContext
1578    * @param bool $required
1579    * @param bool $legacyDate
1580    *   Temporary param to facilitate the conversion of fields to use the datepicker in
1581    *   a controlled way. To convert the field the jcalendar code needs to be removed from the
1582    *   tpl as well. That file is intended to be EOL.
1583    *
1584    * @throws \CiviCRM_API3_Exception
1585    * @throws \Exception
1586    * @return mixed
1587    *   HTML_QuickForm_Element
1588    *   void
1589    */
1590   public function addField($name, $props = [], $required = FALSE, $legacyDate = TRUE) {
1591     // Resolve context.
1592     if (empty($props['context'])) {
1593       $props['context'] = $this->getDefaultContext();
1594     }
1595     $context = $props['context'];
1596     // Resolve entity.
1597     if (empty($props['entity'])) {
1598       $props['entity'] = $this->getDefaultEntity();
1599     }
1600     // Resolve field.
1601     if (empty($props['name'])) {
1602       $props['name'] = strrpos($name, '[') ? rtrim(substr($name, 1 + strrpos($name, '[')), ']') : $name;
1603     }
1604     // Resolve action.
1605     if (empty($props['action'])) {
1606       $props['action'] = $this->getApiAction();
1607     }
1608
1609     // Handle custom fields
1610     if (strpos($name, 'custom_') === 0 && is_numeric($name[7])) {
1611       $fieldId = (int) substr($name, 7);
1612       return CRM_Core_BAO_CustomField::addQuickFormElement($this, $name, $fieldId, $required, $context == 'search', CRM_Utils_Array::value('label', $props));
1613     }
1614
1615     // Core field - get metadata.
1616     $fieldSpec = civicrm_api3($props['entity'], 'getfield', $props);
1617     $fieldSpec = $fieldSpec['values'];
1618     $fieldSpecLabel = $fieldSpec['html']['label'] ?? CRM_Utils_Array::value('title', $fieldSpec);
1619     $label = CRM_Utils_Array::value('label', $props, $fieldSpecLabel);
1620
1621     $widget = $props['type'] ?? $fieldSpec['html']['type'];
1622     if ($widget == 'TextArea' && $context == 'search') {
1623       $widget = 'Text';
1624     }
1625
1626     $isSelect = (in_array($widget, [
1627       'Select',
1628       'Select2',
1629       'CheckBoxGroup',
1630       'RadioGroup',
1631       'Radio',
1632     ]));
1633
1634     if ($isSelect) {
1635       // Fetch options from the api unless passed explicitly.
1636       if (isset($props['options'])) {
1637         $options = $props['options'];
1638       }
1639       else {
1640         $options = $fieldSpec['options'] ?? NULL;
1641       }
1642       if ($context == 'search') {
1643         $widget = $widget == 'Select2' ? $widget : 'Select';
1644         $props['multiple'] = CRM_Utils_Array::value('multiple', $props, TRUE);
1645       }
1646
1647       // Add data for popup link.
1648       $canEditOptions = CRM_Core_Permission::check('administer CiviCRM');
1649       $hasOptionUrl = !empty($props['option_url']);
1650       $optionUrlKeyIsSet = array_key_exists('option_url', $props);
1651       $shouldAdd = $context !== 'search' && $isSelect && $canEditOptions;
1652
1653       // Only add if key is not set, or if non-empty option url is provided
1654       if (($hasOptionUrl || !$optionUrlKeyIsSet) && $shouldAdd) {
1655         $optionUrl = $hasOptionUrl ? $props['option_url'] :
1656           CRM_Core_PseudoConstant::getOptionEditUrl($fieldSpec);
1657         $props['data-option-edit-path'] = $optionUrl;
1658         $props['data-api-entity'] = $props['entity'];
1659         $props['data-api-field'] = $props['name'];
1660       }
1661     }
1662     $props += CRM_Utils_Array::value('html', $fieldSpec, []);
1663     CRM_Utils_Array::remove($props, 'entity', 'name', 'context', 'label', 'action', 'type', 'option_url', 'options');
1664
1665     // TODO: refactor switch statement, to separate methods.
1666     switch ($widget) {
1667       case 'Text':
1668       case 'Url':
1669       case 'Number':
1670       case 'Email':
1671         //TODO: Autodetect ranges
1672         $props['size'] = $props['size'] ?? 60;
1673         return $this->add(strtolower($widget), $name, $label, $props, $required);
1674
1675       case 'hidden':
1676         return $this->add('hidden', $name, NULL, $props, $required);
1677
1678       case 'TextArea':
1679         //Set default columns and rows for textarea.
1680         $props['rows'] = $props['rows'] ?? 4;
1681         $props['cols'] = $props['cols'] ?? 60;
1682         if (empty($props['maxlength']) && isset($fieldSpec['length'])) {
1683           $props['maxlength'] = $fieldSpec['length'];
1684         }
1685         return $this->add('textarea', $name, $label, $props, $required);
1686
1687       case 'Select Date':
1688         // This is a white list for fields that have been tested with
1689         // date picker. We should be able to remove the other
1690         if ($legacyDate) {
1691           //TODO: add range support
1692           //TODO: Add date formats
1693           //TODO: Add javascript template for dates.
1694           return $this->addDate($name, $label, $required, $props);
1695         }
1696         else {
1697           $fieldSpec = CRM_Utils_Date::addDateMetadataToField($fieldSpec, $fieldSpec);
1698           $attributes = ['format' => $fieldSpec['date_format']];
1699           return $this->add('datepicker', $name, $label, $attributes, $required, $fieldSpec['datepicker']['extra']);
1700         }
1701
1702       case 'Radio':
1703         $separator = $props['separator'] ?? NULL;
1704         unset($props['separator']);
1705         if (!isset($props['allowClear'])) {
1706           $props['allowClear'] = !$required;
1707         }
1708         return $this->addRadio($name, $label, $options, $props, $separator, $required);
1709
1710       case 'ChainSelect':
1711         $props += [
1712           'required' => $required,
1713           'label' => $label,
1714           'multiple' => $context == 'search',
1715         ];
1716         return $this->addChainSelect($name, $props);
1717
1718       case 'Select':
1719       case 'Select2':
1720         $props['class'] = CRM_Utils_Array::value('class', $props, 'big') . ' crm-select2';
1721         if (!array_key_exists('placeholder', $props) && $placeholder = self::selectOrAnyPlaceholder($props, $required)) {
1722           $props['placeholder'] = $placeholder;
1723         }
1724         // TODO: Add and/or option for fields that store multiple values
1725         return $this->add(strtolower($widget), $name, $label, $options, $required, $props);
1726
1727       case 'CheckBoxGroup':
1728         return $this->addCheckBox($name, $label, array_flip($options), $required, $props);
1729
1730       case 'RadioGroup':
1731         return $this->addRadio($name, $label, $options, $props, NULL, $required);
1732
1733       case 'CheckBox':
1734         if ($context === 'search') {
1735           $this->addYesNo($name, $label, TRUE, FALSE, $props);
1736           return;
1737         }
1738         $text = $props['text'] ?? NULL;
1739         unset($props['text']);
1740         return $this->addElement('checkbox', $name, $label, $text, $props);
1741
1742       //add support for 'Advcheckbox' field
1743       case 'advcheckbox':
1744         $text = $props['text'] ?? NULL;
1745         unset($props['text']);
1746         return $this->addElement('advcheckbox', $name, $label, $text, $props);
1747
1748       case 'File':
1749         // We should not build upload file in search mode.
1750         if ($context == 'search') {
1751           return;
1752         }
1753         $file = $this->add('file', $name, $label, $props, $required);
1754         $this->addUploadElement($name);
1755         return $file;
1756
1757       case 'RichTextEditor':
1758         return $this->add('wysiwyg', $name, $label, $props, $required);
1759
1760       case 'EntityRef':
1761         return $this->addEntityRef($name, $label, $props, $required);
1762
1763       case 'Password':
1764         $props['size'] = $props['size'] ?? 60;
1765         return $this->add('password', $name, $label, $props, $required);
1766
1767       // Check datatypes of fields
1768       // case 'Int':
1769       //case 'Float':
1770       //case 'Money':
1771       //case read only fields
1772       default:
1773         throw new Exception("Unsupported html-element " . $widget);
1774     }
1775   }
1776
1777   /**
1778    * Add a widget for selecting/editing/creating/copying a profile form
1779    *
1780    * @param string $name
1781    *   HTML form-element name.
1782    * @param string $label
1783    *   Printable label.
1784    * @param string $allowCoreTypes
1785    *   Only present a UFGroup if its group_type includes a subset of $allowCoreTypes; e.g. 'Individual', 'Activity'.
1786    * @param string $allowSubTypes
1787    *   Only present a UFGroup if its group_type is compatible with $allowSubypes.
1788    * @param array $entities
1789    * @param bool $default
1790    *   //CRM-15427.
1791    * @param string $usedFor
1792    */
1793   public function addProfileSelector($name, $label, $allowCoreTypes, $allowSubTypes, $entities, $default = FALSE, $usedFor = NULL) {
1794     // Output widget
1795     // FIXME: Instead of adhoc serialization, use a single json_encode()
1796     CRM_UF_Page_ProfileEditor::registerProfileScripts();
1797     CRM_UF_Page_ProfileEditor::registerSchemas(CRM_Utils_Array::collect('entity_type', $entities));
1798     $this->add('text', $name, $label, [
1799       'class' => 'crm-profile-selector',
1800       // Note: client treats ';;' as equivalent to \0, and ';;' works better in HTML
1801       'data-group-type' => CRM_Core_BAO_UFGroup::encodeGroupType($allowCoreTypes, $allowSubTypes, ';;'),
1802       'data-entities' => json_encode($entities),
1803       //CRM-15427
1804       'data-default' => $default,
1805       'data-usedfor' => json_encode($usedFor),
1806     ]);
1807   }
1808
1809   /**
1810    * @return null
1811    */
1812   public function getRootTitle() {
1813     return NULL;
1814   }
1815
1816   /**
1817    * @return string
1818    */
1819   public function getCompleteTitle() {
1820     return $this->getRootTitle() . $this->getTitle();
1821   }
1822
1823   /**
1824    * @return CRM_Core_Smarty
1825    */
1826   public static function &getTemplate() {
1827     return self::$_template;
1828   }
1829
1830   /**
1831    * @param $elementName
1832    */
1833   public function addUploadElement($elementName) {
1834     $uploadNames = $this->get('uploadNames');
1835     if (!$uploadNames) {
1836       $uploadNames = [];
1837     }
1838     if (is_array($elementName)) {
1839       foreach ($elementName as $name) {
1840         if (!in_array($name, $uploadNames)) {
1841           $uploadNames[] = $name;
1842         }
1843       }
1844     }
1845     else {
1846       if (!in_array($elementName, $uploadNames)) {
1847         $uploadNames[] = $elementName;
1848       }
1849     }
1850     $this->set('uploadNames', $uploadNames);
1851
1852     $config = CRM_Core_Config::singleton();
1853     if (!empty($uploadNames)) {
1854       $this->controller->addUploadAction($config->customFileUploadDir, $uploadNames);
1855     }
1856   }
1857
1858   /**
1859    * @param $name
1860    *
1861    * @return null
1862    */
1863   public function getVar($name) {
1864     return $this->$name ?? NULL;
1865   }
1866
1867   /**
1868    * @param $name
1869    * @param $value
1870    */
1871   public function setVar($name, $value) {
1872     $this->$name = $value;
1873   }
1874
1875   /**
1876    * Add date.
1877    *
1878    * @deprecated
1879    * Use $this->add('datepicker', ...) instead.
1880    *
1881    * @param string $name
1882    *   Name of the element.
1883    * @param string $label
1884    *   Label of the element.
1885    * @param bool $required
1886    *   True if required.
1887    * @param array $attributes
1888    *   Key / value pair.
1889    */
1890   public function addDate($name, $label, $required = FALSE, $attributes = NULL) {
1891     if (!empty($attributes['formatType'])) {
1892       // get actual format
1893       $params = ['name' => $attributes['formatType']];
1894       $values = [];
1895
1896       // cache date information
1897       static $dateFormat;
1898       $key = "dateFormat_" . str_replace(' ', '_', $attributes['formatType']);
1899       if (empty($dateFormat[$key])) {
1900         CRM_Core_DAO::commonRetrieve('CRM_Core_DAO_PreferencesDate', $params, $values);
1901         $dateFormat[$key] = $values;
1902       }
1903       else {
1904         $values = $dateFormat[$key];
1905       }
1906
1907       if ($values['date_format']) {
1908         $attributes['format'] = $values['date_format'];
1909       }
1910
1911       if (!empty($values['time_format'])) {
1912         $attributes['timeFormat'] = $values['time_format'];
1913       }
1914       $attributes['startOffset'] = $values['start'];
1915       $attributes['endOffset'] = $values['end'];
1916     }
1917
1918     $config = CRM_Core_Config::singleton();
1919     if (empty($attributes['format'])) {
1920       $attributes['format'] = $config->dateInputFormat;
1921     }
1922
1923     if (!isset($attributes['startOffset'])) {
1924       $attributes['startOffset'] = 10;
1925     }
1926
1927     if (!isset($attributes['endOffset'])) {
1928       $attributes['endOffset'] = 10;
1929     }
1930
1931     $this->add('text', $name, $label, $attributes);
1932
1933     if (!empty($attributes['addTime']) || !empty($attributes['timeFormat'])) {
1934
1935       if (!isset($attributes['timeFormat'])) {
1936         $timeFormat = $config->timeInputFormat;
1937       }
1938       else {
1939         $timeFormat = $attributes['timeFormat'];
1940       }
1941
1942       // 1 - 12 hours and 2 - 24 hours, but for jquery widget it is 0 and 1 respectively
1943       if ($timeFormat) {
1944         $show24Hours = TRUE;
1945         if ($timeFormat == 1) {
1946           $show24Hours = FALSE;
1947         }
1948
1949         //CRM-6664 -we are having time element name
1950         //in either flat string or an array format.
1951         $elementName = $name . '_time';
1952         if (substr($name, -1) == ']') {
1953           $elementName = substr($name, 0, strlen($name) - 1) . '_time]';
1954         }
1955
1956         $this->add('text', $elementName, ts('Time'), ['timeFormat' => $show24Hours]);
1957       }
1958     }
1959
1960     if ($required) {
1961       $this->addRule($name, ts('Please select %1', [1 => $label]), 'required');
1962       if (!empty($attributes['addTime']) && !empty($attributes['addTimeRequired'])) {
1963         $this->addRule($elementName, ts('Please enter a time.'), 'required');
1964       }
1965     }
1966   }
1967
1968   /**
1969    * Function that will add date and time.
1970    *
1971    * @deprecated
1972    * Use $this->add('datepicker', ...) instead.
1973    *
1974    * @param string $name
1975    * @param string $label
1976    * @param bool $required
1977    * @param null $attributes
1978    */
1979   public function addDateTime($name, $label, $required = FALSE, $attributes = NULL) {
1980     $addTime = ['addTime' => TRUE];
1981     if (is_array($attributes)) {
1982       $attributes = array_merge($attributes, $addTime);
1983     }
1984     else {
1985       $attributes = $addTime;
1986     }
1987
1988     $this->addDate($name, $label, $required, $attributes);
1989   }
1990
1991   /**
1992    * Add a currency and money element to the form.
1993    *
1994    * @param string $name
1995    * @param string $label
1996    * @param bool $required
1997    * @param null $attributes
1998    * @param bool $addCurrency
1999    * @param string $currencyName
2000    * @param null $defaultCurrency
2001    * @param bool $freezeCurrency
2002    *
2003    * @return \HTML_QuickForm_Element
2004    */
2005   public function addMoney(
2006     $name,
2007     $label,
2008     $required = FALSE,
2009     $attributes = NULL,
2010     $addCurrency = TRUE,
2011     $currencyName = 'currency',
2012     $defaultCurrency = NULL,
2013     $freezeCurrency = FALSE
2014   ) {
2015     $element = $this->add('text', $name, $label, $attributes, $required);
2016     $this->addRule($name, ts('Please enter a valid amount.'), 'money');
2017
2018     if ($addCurrency) {
2019       $ele = $this->addCurrency($currencyName, NULL, TRUE, $defaultCurrency, $freezeCurrency);
2020     }
2021
2022     return $element;
2023   }
2024
2025   /**
2026    * Add currency element to the form.
2027    *
2028    * @param string $name
2029    * @param null $label
2030    * @param bool $required
2031    * @param string $defaultCurrency
2032    * @param bool $freezeCurrency
2033    * @param bool $setDefaultCurrency
2034    */
2035   public function addCurrency(
2036     $name = 'currency',
2037     $label = NULL,
2038     $required = TRUE,
2039     $defaultCurrency = NULL,
2040     $freezeCurrency = FALSE,
2041     $setDefaultCurrency = TRUE
2042   ) {
2043     $currencies = CRM_Core_OptionGroup::values('currencies_enabled');
2044     if (!empty($defaultCurrency) && !array_key_exists($defaultCurrency, $currencies)) {
2045       Civi::log()->warning('addCurrency: Currency ' . $defaultCurrency . ' is disabled but still in use!');
2046       $currencies[$defaultCurrency] = $defaultCurrency;
2047     }
2048     $options = ['class' => 'crm-select2 eight'];
2049     if (!$required) {
2050       $currencies = ['' => ''] + $currencies;
2051       $options['placeholder'] = ts('- none -');
2052     }
2053     $ele = $this->add('select', $name, $label, $currencies, $required, $options);
2054     if ($freezeCurrency) {
2055       $ele->freeze();
2056     }
2057     if (!$defaultCurrency) {
2058       $config = CRM_Core_Config::singleton();
2059       $defaultCurrency = $config->defaultCurrency;
2060     }
2061     // In some case, setting currency field by default might override the default value
2062     //  as encountered in CRM-20527 for batch data entry
2063     if ($setDefaultCurrency) {
2064       $this->setDefaults([$name => $defaultCurrency]);
2065     }
2066   }
2067
2068   /**
2069    * Create a single or multiple entity ref field.
2070    * @param string $name
2071    * @param string $label
2072    * @param array $props
2073    *   Mix of html and widget properties, including:.
2074    *   - select - params to give to select2 widget
2075    *   - entity - defaults to Contact
2076    *   - create - can the user create a new entity on-the-fly?
2077    *             Set to TRUE if entity is contact and you want the default profiles,
2078    *             or pass in your own set of links. @see CRM_Campaign_BAO_Campaign::getEntityRefCreateLinks for format
2079    *             note that permissions are checked automatically
2080    *   - api - array of settings for the getlist api wrapper
2081    *          note that it accepts a 'params' setting which will be passed to the underlying api
2082    *   - placeholder - string
2083    *   - multiple - bool
2084    *   - class, etc. - other html properties
2085    * @param bool $required
2086    *
2087    * @return HTML_QuickForm_Element
2088    */
2089   public function addEntityRef($name, $label = '', $props = [], $required = FALSE) {
2090     // Default properties
2091     $props['api'] = CRM_Utils_Array::value('api', $props, []);
2092     $props['entity'] = CRM_Core_DAO_AllCoreTables::convertEntityNameToCamel($props['entity'] ?? 'Contact');
2093     $props['class'] = ltrim(($props['class'] ?? '') . ' crm-form-entityref');
2094
2095     if (array_key_exists('create', $props) && empty($props['create'])) {
2096       unset($props['create']);
2097     }
2098
2099     $props['placeholder'] = $props['placeholder'] ?? self::selectOrAnyPlaceholder($props, $required);
2100
2101     $defaults = [];
2102     if (!empty($props['multiple'])) {
2103       $defaults['multiple'] = TRUE;
2104     }
2105     $props['select'] = CRM_Utils_Array::value('select', $props, []) + $defaults;
2106
2107     $this->formatReferenceFieldAttributes($props, get_class($this));
2108     return $this->add('text', $name, $label, $props, $required);
2109   }
2110
2111   /**
2112    * @param array $props
2113    * @param string $formName
2114    */
2115   private function formatReferenceFieldAttributes(&$props, $formName) {
2116     CRM_Utils_Hook::alterEntityRefParams($props, $formName);
2117     $props['data-select-params'] = json_encode($props['select']);
2118     $props['data-api-params'] = $props['api'] ? json_encode($props['api']) : NULL;
2119     $props['data-api-entity'] = $props['entity'];
2120     if (!empty($props['create'])) {
2121       $props['data-create-links'] = json_encode($props['create']);
2122     }
2123     CRM_Utils_Array::remove($props, 'multiple', 'select', 'api', 'entity', 'create');
2124   }
2125
2126   /**
2127    * Convert all date fields within the params to mysql date ready for the
2128    * BAO layer. In this case fields are checked against the $_datefields defined for the form
2129    * and if time is defined it is incorporated
2130    *
2131    * @param array $params
2132    *   Input params from the form.
2133    *
2134    * @todo it would probably be better to work on $this->_params than a passed array
2135    * @todo standardise the format which dates are passed to the BAO layer in & remove date
2136    * handling from BAO
2137    */
2138   public function convertDateFieldsToMySQL(&$params) {
2139     foreach ($this->_dateFields as $fieldName => $specs) {
2140       if (!empty($params[$fieldName])) {
2141         $params[$fieldName] = CRM_Utils_Date::isoToMysql(
2142           CRM_Utils_Date::processDate(
2143             $params[$fieldName],
2144             CRM_Utils_Array::value("{$fieldName}_time", $params), TRUE)
2145         );
2146       }
2147       else {
2148         if (isset($specs['default'])) {
2149           $params[$fieldName] = date('YmdHis', strtotime($specs['default']));
2150         }
2151       }
2152     }
2153   }
2154
2155   /**
2156    * @param $elementName
2157    */
2158   public function removeFileRequiredRules($elementName) {
2159     $this->_required = array_diff($this->_required, [$elementName]);
2160     if (isset($this->_rules[$elementName])) {
2161       foreach ($this->_rules[$elementName] as $index => $ruleInfo) {
2162         if ($ruleInfo['type'] == 'uploadedfile') {
2163           unset($this->_rules[$elementName][$index]);
2164         }
2165       }
2166       if (empty($this->_rules[$elementName])) {
2167         unset($this->_rules[$elementName]);
2168       }
2169     }
2170   }
2171
2172   /**
2173    * Function that can be defined in Form to override or.
2174    * perform specific action on cancel action
2175    */
2176   public function cancelAction() {
2177   }
2178
2179   /**
2180    * Helper function to verify that required fields have been filled.
2181    *
2182    * Typically called within the scope of a FormRule function
2183    *
2184    * @param array $fields
2185    * @param array $values
2186    * @param array $errors
2187    */
2188   public static function validateMandatoryFields($fields, $values, &$errors) {
2189     foreach ($fields as $name => $fld) {
2190       if (!empty($fld['is_required']) && CRM_Utils_System::isNull(CRM_Utils_Array::value($name, $values))) {
2191         $errors[$name] = ts('%1 is a required field.', [1 => $fld['title']]);
2192       }
2193     }
2194   }
2195
2196   /**
2197    * Get contact if for a form object. Prioritise
2198    *   - cid in URL if 0 (on behalf on someoneelse)
2199    *      (@todo consider setting a variable if onbehalf for clarity of downstream 'if's
2200    *   - logged in user id if it matches the one in the cid in the URL
2201    *   - contact id validated from a checksum from a checksum
2202    *   - cid from the url if the caller has ACL permission to view
2203    *   - fallback is logged in user (or ? NULL if no logged in user) (@todo wouldn't 0 be more intuitive?)
2204    *
2205    * @return NULL|int
2206    */
2207   protected function setContactID() {
2208     $tempID = CRM_Utils_Request::retrieve('cid', 'Positive', $this);
2209     if (isset($this->_params) && !empty($this->_params['select_contact_id'])) {
2210       $tempID = $this->_params['select_contact_id'];
2211     }
2212     if (isset($this->_params, $this->_params[0]) && !empty($this->_params[0]['select_contact_id'])) {
2213       // event form stores as an indexed array, contribution form not so much...
2214       $tempID = $this->_params[0]['select_contact_id'];
2215     }
2216
2217     // force to ignore the authenticated user
2218     if ($tempID === '0' || $tempID === 0) {
2219       // we set the cid on the form so that this will be retained for the Confirm page
2220       // in the multi-page form & prevent us returning the $userID when this is called
2221       // from that page
2222       // we don't really need to set it when $tempID is set because the params have that stored
2223       $this->set('cid', 0);
2224       CRM_Core_Resources::singleton()->addVars('coreForm', ['contact_id' => (int) $tempID]);
2225       return (int) $tempID;
2226     }
2227
2228     $userID = $this->getLoggedInUserContactID();
2229
2230     if (!is_null($tempID) && $tempID === $userID) {
2231       CRM_Core_Resources::singleton()->addVars('coreForm', ['contact_id' => (int) $tempID]);
2232       return (int) $userID;
2233     }
2234
2235     //check if this is a checksum authentication
2236     $userChecksum = CRM_Utils_Request::retrieve('cs', 'String', $this);
2237     if ($userChecksum) {
2238       //check for anonymous user.
2239       $validUser = CRM_Contact_BAO_Contact_Utils::validChecksum($tempID, $userChecksum);
2240       if ($validUser) {
2241         CRM_Core_Resources::singleton()->addVars('coreForm', ['contact_id' => (int) $tempID]);
2242         CRM_Core_Resources::singleton()->addVars('coreForm', ['checksum' => $userChecksum]);
2243         return $tempID;
2244       }
2245     }
2246     // check if user has permission, CRM-12062
2247     elseif ($tempID && CRM_Contact_BAO_Contact_Permission::allow($tempID)) {
2248       CRM_Core_Resources::singleton()->addVars('coreForm', ['contact_id' => (int) $tempID]);
2249       return $tempID;
2250     }
2251     if (is_numeric($userID)) {
2252       CRM_Core_Resources::singleton()->addVars('coreForm', ['contact_id' => (int) $userID]);
2253     }
2254     return is_numeric($userID) ? $userID : NULL;
2255   }
2256
2257   /**
2258    * Get the contact id that the form is being submitted for.
2259    *
2260    * @return int|null
2261    */
2262   public function getContactID() {
2263     return $this->setContactID();
2264   }
2265
2266   /**
2267    * Get the contact id of the logged in user.
2268    *
2269    * @return int|false
2270    */
2271   public function getLoggedInUserContactID() {
2272     // check if the user is logged in and has a contact ID
2273     $session = CRM_Core_Session::singleton();
2274     return $session->get('userID') ? (int) $session->get('userID') : FALSE;
2275   }
2276
2277   /**
2278    * Add autoselector field -if user has permission to view contacts
2279    * If adding this to a form you also need to add to the tpl e.g
2280    *
2281    * {if !empty($selectable)}
2282    * <div class="crm-summary-row">
2283    *   <div class="crm-label">{$form.select_contact.label}</div>
2284    *   <div class="crm-content">
2285    *     {$form.select_contact.html}
2286    *   </div>
2287    * </div>
2288    * {/if}
2289    *
2290    * @param array $profiles
2291    *   Ids of profiles that are on the form (to be autofilled).
2292    * @param array $autoCompleteField
2293    *
2294    *   - name_field
2295    *   - id_field
2296    *   - url (for ajax lookup)
2297    *
2298    * @throws \CRM_Core_Exception
2299    * @todo add data attributes so we can deal with multiple instances on a form
2300    */
2301   public function addAutoSelector($profiles = [], $autoCompleteField = []) {
2302     $autoCompleteField = array_merge([
2303       'id_field' => 'select_contact_id',
2304       'placeholder' => ts('Select someone else ...'),
2305       'show_hide' => TRUE,
2306       'api' => ['params' => ['contact_type' => 'Individual']],
2307     ], $autoCompleteField);
2308
2309     if ($this->canUseAjaxContactLookups()) {
2310       $this->assign('selectable', $autoCompleteField['id_field']);
2311       $this->addEntityRef($autoCompleteField['id_field'], NULL, [
2312         'placeholder' => $autoCompleteField['placeholder'],
2313         'api' => $autoCompleteField['api'],
2314       ]);
2315
2316       CRM_Core_Resources::singleton()->addScriptFile('civicrm', 'js/AlternateContactSelector.js', 1, 'html-header')
2317         ->addSetting([
2318           'form' => ['autocompletes' => $autoCompleteField],
2319           'ids' => ['profile' => $profiles],
2320         ]);
2321     }
2322   }
2323
2324   /**
2325    */
2326   public function canUseAjaxContactLookups() {
2327     if (0 < (civicrm_api3('contact', 'getcount', ['check_permissions' => 1])) &&
2328       CRM_Core_Permission::check([['access AJAX API', 'access CiviCRM']])
2329     ) {
2330       return TRUE;
2331     }
2332   }
2333
2334   /**
2335    * Add the options appropriate to cid = zero - ie. autocomplete
2336    *
2337    * @todo there is considerable code duplication between the contribution forms & event forms. It is apparent
2338    * that small pieces of duplication are not being refactored into separate functions because their only shared parent
2339    * is this form. Inserting a class FrontEndForm.php between the contribution & event & this class would allow functions like this
2340    * and a dozen other small ones to be refactored into a shared parent with the reduction of much code duplication
2341    */
2342   public function addCIDZeroOptions() {
2343     $this->assign('nocid', TRUE);
2344     $profiles = [];
2345     if ($this->_values['custom_pre_id']) {
2346       $profiles[] = $this->_values['custom_pre_id'];
2347     }
2348     if ($this->_values['custom_post_id']) {
2349       $profiles = array_merge($profiles, (array) $this->_values['custom_post_id']);
2350     }
2351     $profiles[] = 'billing';
2352     if (!empty($this->_values)) {
2353       $this->addAutoSelector($profiles);
2354     }
2355   }
2356
2357   /**
2358    * Set default values on form for given contact (or no contact defaults)
2359    *
2360    * @param mixed $profile_id
2361    *   (can be id, or profile name).
2362    * @param int $contactID
2363    *
2364    * @return array
2365    */
2366   public function getProfileDefaults($profile_id = 'Billing', $contactID = NULL) {
2367     try {
2368       $defaults = civicrm_api3('profile', 'getsingle', [
2369         'profile_id' => (array) $profile_id,
2370         'contact_id' => $contactID,
2371       ]);
2372       return $defaults;
2373     }
2374     catch (Exception $e) {
2375       // the try catch block gives us silent failure -not 100% sure this is a good idea
2376       // as silent failures are often worse than noisy ones
2377       return [];
2378     }
2379   }
2380
2381   /**
2382    * Sets form attribute.
2383    * @see CRM.loadForm
2384    */
2385   public function preventAjaxSubmit() {
2386     $this->setAttribute('data-no-ajax-submit', 'true');
2387   }
2388
2389   /**
2390    * Sets form attribute.
2391    * @see CRM.loadForm
2392    */
2393   public function allowAjaxSubmit() {
2394     $this->removeAttribute('data-no-ajax-submit');
2395   }
2396
2397   /**
2398    * Sets page title based on entity and action.
2399    * @param string $entityLabel
2400    */
2401   public function setPageTitle($entityLabel) {
2402     switch ($this->_action) {
2403       case CRM_Core_Action::ADD:
2404         CRM_Utils_System::setTitle(ts('New %1', [1 => $entityLabel]));
2405         break;
2406
2407       case CRM_Core_Action::UPDATE:
2408         CRM_Utils_System::setTitle(ts('Edit %1', [1 => $entityLabel]));
2409         break;
2410
2411       case CRM_Core_Action::VIEW:
2412       case CRM_Core_Action::PREVIEW:
2413         CRM_Utils_System::setTitle(ts('View %1', [1 => $entityLabel]));
2414         break;
2415
2416       case CRM_Core_Action::DELETE:
2417         CRM_Utils_System::setTitle(ts('Delete %1', [1 => $entityLabel]));
2418         break;
2419     }
2420   }
2421
2422   /**
2423    * Create a chain-select target field. All settings are optional; the defaults usually work.
2424    *
2425    * @param string $elementName
2426    * @param array $settings
2427    *
2428    * @return HTML_QuickForm_Element
2429    */
2430   public function addChainSelect($elementName, $settings = []) {
2431     $label = strpos($elementName, 'rovince') ? CRM_Core_DAO_StateProvince::getEntityTitle() : CRM_Core_DAO_County::getEntityTitle();
2432     $props = $settings += [
2433       'control_field' => str_replace(['state_province', 'StateProvince', 'county', 'County'], [
2434         'country',
2435         'Country',
2436         'state_province',
2437         'StateProvince',
2438       ], $elementName),
2439       'data-callback' => strpos($elementName, 'rovince') ? 'civicrm/ajax/jqState' : 'civicrm/ajax/jqCounty',
2440       'label' => $label,
2441       'data-empty-prompt' => strpos($elementName, 'rovince') ? ts('Choose country first') : ts('Choose state first'),
2442       'data-none-prompt' => ts('- N/A -'),
2443       'multiple' => FALSE,
2444       'required' => FALSE,
2445       'placeholder' => ts('- select %1 -', [1 => $label]),
2446     ];
2447     CRM_Utils_Array::remove($props, 'label', 'required', 'control_field', 'context');
2448     $props['class'] = (empty($props['class']) ? '' : "{$props['class']} ") . 'crm-select2';
2449     $props['data-select-prompt'] = $props['placeholder'];
2450     $props['data-name'] = $elementName;
2451
2452     $this->_chainSelectFields[$settings['control_field']] = $elementName;
2453
2454     // Passing NULL instead of an array of options
2455     // CRM-15225 - normally QF will reject any selected values that are not part of the field's options, but due to a
2456     // quirk in our patched version of HTML_QuickForm_select, this doesn't happen if the options are NULL
2457     // which seems a bit dirty but it allows our dynamically-popuplated select element to function as expected.
2458     return $this->add('select', $elementName, $settings['label'], NULL, $settings['required'], $props);
2459   }
2460
2461   /**
2462    * Add actions menu to results form.
2463    *
2464    * @param array $tasks
2465    */
2466   public function addTaskMenu($tasks) {
2467     if (is_array($tasks) && !empty($tasks)) {
2468       // Set constants means this will always load with an empty value, not reloading any submitted value.
2469       // This is appropriate as it is a pseudofield.
2470       $this->setConstants(['task' => '']);
2471       $this->assign('taskMetaData', $tasks);
2472       $select = $this->add('select', 'task', NULL, ['' => ts('Actions')], FALSE, [
2473         'class' => 'crm-select2 crm-action-menu fa-check-circle-o huge crm-search-result-actions',
2474       ]
2475       );
2476       foreach ($tasks as $key => $task) {
2477         $attributes = [];
2478         if (isset($task['data'])) {
2479           foreach ($task['data'] as $dataKey => $dataValue) {
2480             $attributes['data-' . $dataKey] = $dataValue;
2481           }
2482         }
2483         $select->addOption($task['title'], $key, $attributes);
2484       }
2485       if (empty($this->_actionButtonName)) {
2486         $this->_actionButtonName = $this->getButtonName('next', 'action');
2487       }
2488       $this->assign('actionButtonName', $this->_actionButtonName);
2489       $this->add('xbutton', $this->_actionButtonName, ts('Go'), [
2490         'type' => 'submit',
2491         'class' => 'hiddenElement crm-search-go-button',
2492       ]);
2493
2494       // Radio to choose "All items" or "Selected items only"
2495       $selectedRowsRadio = $this->addElement('radio', 'radio_ts', NULL, '', 'ts_sel', ['checked' => 'checked']);
2496       $allRowsRadio = $this->addElement('radio', 'radio_ts', NULL, '', 'ts_all');
2497       $this->assign('ts_sel_id', $selectedRowsRadio->_attributes['id']);
2498       $this->assign('ts_all_id', $allRowsRadio->_attributes['id']);
2499
2500       CRM_Core_Resources::singleton()->addScriptFile('civicrm', 'js/crm.searchForm.js', 1, 'html-header');
2501     }
2502   }
2503
2504   /**
2505    * Set options and attributes for chain select fields based on the controlling field's value
2506    */
2507   private function preProcessChainSelectFields() {
2508     foreach ($this->_chainSelectFields as $control => $target) {
2509       // The 'target' might get missing if extensions do removeElement() in a form hook.
2510       if ($this->elementExists($target)) {
2511         $targetField = $this->getElement($target);
2512         $targetType = $targetField->getAttribute('data-callback') == 'civicrm/ajax/jqCounty' ? 'county' : 'stateProvince';
2513         $options = [];
2514         // If the control field is on the form, setup chain-select and dynamically populate options
2515         if ($this->elementExists($control)) {
2516           $controlField = $this->getElement($control);
2517           $controlType = $targetType == 'county' ? 'stateProvince' : 'country';
2518
2519           $targetField->setAttribute('class', $targetField->getAttribute('class') . ' crm-chain-select-target');
2520
2521           $css = (string) $controlField->getAttribute('class');
2522           $controlField->updateAttributes([
2523             'class' => ($css ? "$css " : 'crm-select2 ') . 'crm-chain-select-control',
2524             'data-target' => $target,
2525           ]);
2526           $controlValue = $controlField->getValue();
2527           if ($controlValue) {
2528             $options = CRM_Core_BAO_Location::getChainSelectValues($controlValue, $controlType, TRUE);
2529             if (!$options) {
2530               $targetField->setAttribute('placeholder', $targetField->getAttribute('data-none-prompt'));
2531             }
2532           }
2533           else {
2534             $targetField->setAttribute('placeholder', $targetField->getAttribute('data-empty-prompt'));
2535             $targetField->setAttribute('disabled', 'disabled');
2536           }
2537         }
2538         // Control field not present - fall back to loading default options
2539         else {
2540           $options = CRM_Core_PseudoConstant::$targetType();
2541         }
2542         if (!$targetField->getAttribute('multiple')) {
2543           $options = ['' => $targetField->getAttribute('placeholder')] + $options;
2544           $targetField->removeAttribute('placeholder');
2545         }
2546         $targetField->_options = [];
2547         $targetField->loadArray($options);
2548       }
2549     }
2550   }
2551
2552   /**
2553    * Validate country / state / county match and suppress unwanted "required" errors
2554    */
2555   private function validateChainSelectFields() {
2556     foreach ($this->_chainSelectFields as $control => $target) {
2557       if ($this->elementExists($control) && $this->elementExists($target)) {
2558         $controlValue = (array) $this->getElementValue($control);
2559         $targetField = $this->getElement($target);
2560         $controlType = $targetField->getAttribute('data-callback') == 'civicrm/ajax/jqCounty' ? 'stateProvince' : 'country';
2561         $targetValue = array_filter((array) $targetField->getValue());
2562         if ($targetValue || $this->getElementError($target)) {
2563           $options = CRM_Core_BAO_Location::getChainSelectValues($controlValue, $controlType, TRUE);
2564           if ($targetValue) {
2565             if (!array_intersect($targetValue, array_keys($options))) {
2566               $this->setElementError($target, $controlType == 'country' ? ts('State/Province does not match the selected Country') : ts('County does not match the selected State/Province'));
2567             }
2568           }
2569           // Suppress "required" error for field if it has no options
2570           elseif (!$options) {
2571             $this->setElementError($target, NULL);
2572           }
2573         }
2574       }
2575     }
2576   }
2577
2578   /**
2579    * Assign billing name to the template.
2580    *
2581    * @param array $params
2582    *   Form input params, default to $this->_params.
2583    *
2584    * @return string
2585    */
2586   public function assignBillingName($params = []) {
2587     $name = '';
2588     if (empty($params)) {
2589       $params = $this->_params;
2590     }
2591     if (!empty($params['billing_first_name'])) {
2592       $name = $params['billing_first_name'];
2593     }
2594
2595     if (!empty($params['billing_middle_name'])) {
2596       $name .= " {$params['billing_middle_name']}";
2597     }
2598
2599     if (!empty($params['billing_last_name'])) {
2600       $name .= " {$params['billing_last_name']}";
2601     }
2602     $name = trim($name);
2603     $this->assign('billingName', $name);
2604     return $name;
2605   }
2606
2607   /**
2608    * Get the currency for the form.
2609    *
2610    * @todo this should be overriden on the forms rather than having this
2611    * historic, possible handling in here. As we clean that up we should
2612    * add deprecation notices into here.
2613    *
2614    * @param array $submittedValues
2615    *   Array allowed so forms inheriting this class do not break.
2616    *   Ideally we would make a clear standard around how submitted values
2617    *   are stored (is $this->_values consistently doing that?).
2618    *
2619    * @return string
2620    */
2621   public function getCurrency($submittedValues = []) {
2622     $currency = $this->_values['currency'] ?? NULL;
2623     // For event forms, currency is in a different spot
2624     if (empty($currency)) {
2625       $currency = CRM_Utils_Array::value('currency', CRM_Utils_Array::value('event', $this->_values));
2626     }
2627     if (empty($currency)) {
2628       $currency = CRM_Utils_Request::retrieveValue('currency', 'String');
2629     }
2630     // @todo If empty there is a problem - we should probably put in a deprecation notice
2631     // to warn if that seems to be happening.
2632     return $currency;
2633   }
2634
2635   /**
2636    * Is the form in view or edit mode.
2637    *
2638    * The 'addField' function relies on the form action being one of a set list
2639    * of actions. Checking for these allows for an early return.
2640    *
2641    * @return bool
2642    */
2643   protected function isFormInViewOrEditMode() {
2644     return $this->isFormInViewMode() || $this->isFormInEditMode();
2645   }
2646
2647   /**
2648    * Is the form in edit mode.
2649    *
2650    * Helper function, notably for extensions implementing the buildForm hook,
2651    * so that they can return early.
2652    *
2653    * @return bool
2654    */
2655   public function isFormInEditMode() {
2656     return in_array($this->_action, [
2657       CRM_Core_Action::UPDATE,
2658       CRM_Core_Action::ADD,
2659       CRM_Core_Action::BROWSE,
2660       CRM_Core_Action::BASIC,
2661       CRM_Core_Action::ADVANCED,
2662       CRM_Core_Action::PREVIEW,
2663     ]);
2664   }
2665
2666   /**
2667    * Is the form in view mode.
2668    *
2669    * Helper function, notably for extensions implementing the buildForm hook,
2670    * so that they can return early.
2671    *
2672    * @return bool
2673    */
2674   public function isFormInViewMode() {
2675     return $this->_action == CRM_Core_Action::VIEW;
2676   }
2677
2678   /**
2679    * Set the active tab
2680    *
2681    * @param string $default
2682    *
2683    * @throws \CRM_Core_Exception
2684    */
2685   public function setSelectedChild($default = NULL) {
2686     $selectedChild = CRM_Utils_Request::retrieve('selectedChild', 'Alphanumeric', $this, FALSE, $default);
2687     if (!empty($selectedChild)) {
2688       $this->set('selectedChild', $selectedChild);
2689       $this->assign('selectedChild', $selectedChild);
2690     }
2691   }
2692
2693   /**
2694    * Get the contact if from the url, using the checksum or the cid if it is the logged in user.
2695    *
2696    * This function returns the user being validated. It is not intended to get another user
2697    * they have permission to (setContactID does do that) and can be used to check if the user is
2698    * accessing their own record.
2699    *
2700    * @return int|false
2701    * @throws \CRM_Core_Exception
2702    */
2703   protected function getContactIDIfAccessingOwnRecord() {
2704     $contactID = (int) CRM_Utils_Request::retrieve('cid', 'Positive', $this);
2705     if (!$contactID) {
2706       return FALSE;
2707     }
2708     if ($contactID === $this->getLoggedInUserContactID()) {
2709       return $contactID;
2710     }
2711     $userChecksum = CRM_Utils_Request::retrieve('cs', 'String', $this);
2712     return CRM_Contact_BAO_Contact_Utils::validChecksum($contactID, $userChecksum) ? $contactID : FALSE;
2713   }
2714
2715 }