CRM/Core/Form.php

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