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