CRM/Core/Form.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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-2014
  35  * $Id$
  36  *
  37  */
  38
  39 require_once 'HTML/QuickForm/Page.php';
  40
  41 /**
  42  * Class CRM_Core_Form
  43  */
  44 class CRM_Core_Form extends HTML_QuickForm_Page {
  45
  46   /**
  47    * The state object that this form belongs to
  48    * @var object
  49    */
  50   protected $_state;
  51
  52   /**
  53    * The name of this form
  54    * @var string
  55    */
  56   protected $_name;
  57
  58   /**
  59    * The title of this form
  60    * @var string
  61    */
  62   protected $_title = NULL;
  63
  64   /**
  65    * The options passed into this form
  66    * @var mixed
  67    */
  68   protected $_options = NULL;
  69
  70   /**
  71    * The mode of operation for this form
  72    * @var int
  73    */
  74   protected $_action;
  75
  76   /**
  77    * the renderer used for this form
  78    *
  79    * @var object
  80    */
  81   protected $_renderer;
  82
  83   /**
  84    * An array to hold a list of datefields on the form
  85    * so that they can be converted to ISO in a consistent manner
  86    *
  87    * @var array
  88    *
  89    * e.g on a form declare $_dateFields = array(
  90    *  'receive_date' => array('default' => 'now'),
  91    *  );
  92    *  then in postProcess call $this->convertDateFieldsToMySQL($formValues)
  93    *  to have the time field re-incorporated into the field & 'now' set if
  94    *  no value has been passed in
  95    */
  96   protected $_dateFields = array();
  97
  98   /**
  99    * cache the smarty template for efficiency reasons
 100    *
 101    * @var CRM_Core_Smarty
 102    */
 103   static protected $_template;
 104
 105   /**
 106    *  Indicate if this form should warn users of unsaved changes
 107    */
 108   protected $unsavedChangesWarn;
 109
 110   /**
 111    * What to return to the client if in ajax mode (snippet=json)
 112    *
 113    * @var array
 114    */
 115   public $ajaxResponse = array();
 116
 117   /**
 118    * Url path used to reach this page
 119    *
 120    * @var array
 121    */
 122   public $urlPath = array();
 123
 124   /**
 125    * @var CRM_Core_Controller
 126    */
 127   public $controller;
 128
 129   /**
 130    * constants for attributes for various form elements
 131    * attempt to standardize on the number of variations that we
 132    * use of the below form elements
 133    *
 134    * @var const string
 135    */
 136   CONST ATTR_SPACING = '&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;';
 137
 138   /**
 139    * All checkboxes are defined with a common prefix. This allows us to
 140    * have the same javascript to check / clear all the checkboxes etc
 141    * If u have multiple groups of checkboxes, you will need to give them different
 142    * ids to avoid potential name collision
 143    *
 144    * @var string|int
 145    */
 146   CONST CB_PREFIX = 'mark_x_', CB_PREFIY = 'mark_y_', CB_PREFIZ = 'mark_z_', CB_PREFIX_LEN = 7;
 147
 148   /**
 149    * @internal to keep track of chain-select fields
 150    * @var array
 151    */
 152   private $_chainSelectFields = array();
 153
 154   /**
 155    * Constructor for the basic form page
 156    *
 157    * We should not use QuickForm directly. This class provides a lot
 158    * of default convenient functions, rules and buttons
 159    *
 160    * @param object $state State associated with this form
 161    * @param \const|\enum|int $action The mode the form is operating in (None/Create/View/Update/Delete)
 162    * @param string $method The type of http method used (GET/POST)
 163    * @param string $name The name of the form if different from class name
 164    *
 165    * @return \CRM_Core_Form
 166    * @access public
 167    */
 168   function __construct(
 169     $state = NULL,
 170     $action = CRM_Core_Action::NONE,
 171     $method = 'post',
 172     $name   = NULL
 173   ) {
 174
 175     if ($name) {
 176       $this->_name = $name;
 177     }
 178     else {
 179       // CRM-15153 - FIXME this name translates to a DOM id and is not always unique!
 180       $this->_name = CRM_Utils_String::getClassName(CRM_Utils_System::getClassName($this));
 181     }
 182
 183     $this->HTML_QuickForm_Page($this->_name, $method);
 184
 185     $this->_state =& $state;
 186     if ($this->_state) {
 187       $this->_state->setName($this->_name);
 188     }
 189     $this->_action = (int) $action;
 190
 191     $this->registerRules();
 192
 193     // let the constructor initialize this, should happen only once
 194     if (!isset(self::$_template)) {
 195       self::$_template = CRM_Core_Smarty::singleton();
 196     }
 197     // Workaround for CRM-15153 - give each form a reasonably unique css class
 198     $this->addClass(CRM_Utils_System::getClassName($this));
 199
 200     $this->assign('snippet', CRM_Utils_Array::value('snippet', $_GET));
 201   }
 202
 203   static function generateID() {
 204   }
 205
 206   /**
 207    * Add one or more css classes to the form
 208    * @param $className
 209    */
 210   public function addClass($className) {
 211     $classes = $this->getAttribute('class');
 212     $this->setAttribute('class', ($classes ? "$classes " : '') . $className);
 213   }
 214
 215   /**
 216    * register all the standard rules that most forms potentially use
 217    *
 218    * @return void
 219    * @access private
 220    *
 221    */
 222   function registerRules() {
 223     static $rules = array(
 224       'title', 'longTitle', 'variable', 'qfVariable',
 225       'phone', 'integer', 'query',
 226       'url', 'wikiURL',
 227       'domain', 'numberOfDigit',
 228       'date', 'currentDate',
 229       'asciiFile', 'htmlFile', 'utf8File',
 230       'objectExists', 'optionExists', 'postalCode', 'money', 'positiveInteger',
 231       'xssString', 'fileExists', 'autocomplete', 'validContact',
 232     );
 233
 234     foreach ($rules as $rule) {
 235       $this->registerRule($rule, 'callback', $rule, 'CRM_Utils_Rule');
 236     }
 237   }
 238
 239   /**
 240    * Simple easy to use wrapper around addElement. Deal with
 241    * simple validation rules
 242    *
 243    * @param string $type
 244    * @param string $name
 245    * @param string $label
 246    * @param string|array $attributes (options for select elements)
 247    * @param bool $required
 248    * @param array $extra (attributes for select elements)
 249    *
 250    * @return HTML_QuickForm_Element could be an error object
 251    * @access public
 252    */
 253   function &add($type, $name, $label = '',
 254     $attributes = '', $required = FALSE, $extra = NULL
 255   ) {
 256     if ($type == 'select' && is_array($extra)) {
 257       // Normalize this property
 258       if (!empty($extra['multiple'])) {
 259         $extra['multiple'] = 'multiple';
 260       }
 261       else {
 262         unset($extra['multiple']);
 263       }
 264       // Add placeholder option for select
 265       if (isset($extra['placeholder'])) {
 266         if ($extra['placeholder'] === TRUE) {
 267           $extra['placeholder'] = $required ? ts('- select -') : ts('- none -');
 268         }
 269         if (($extra['placeholder'] || $extra['placeholder'] === '') && empty($extra['multiple']) && is_array($attributes) && !isset($attributes[''])) {
 270           $attributes = array('' => $extra['placeholder']) + $attributes;
 271         }
 272       }
 273     }
 274     $element = $this->addElement($type, $name, $label, $attributes, $extra);
 275     if (HTML_QuickForm::isError($element)) {
 276       CRM_Core_Error::fatal(HTML_QuickForm::errorMessage($element));
 277     }
 278
 279     if ($required) {
 280       if ($type == 'file') {
 281         $error = $this->addRule($name, ts('%1 is a required field.', array(1 => $label)), 'uploadedfile');
 282       }
 283       else {
 284         $error = $this->addRule($name, ts('%1 is a required field.', array(1 => $label)), 'required');
 285       }
 286       if (HTML_QuickForm::isError($error)) {
 287         CRM_Core_Error::fatal(HTML_QuickForm::errorMessage($element));
 288       }
 289     }
 290
 291     return $element;
 292   }
 293
 294   /**
 295    * This function is called before buildForm. Any pre-processing that
 296    * needs to be done for buildForm should be done here
 297    *
 298    * This is a virtual function and should be redefined if needed
 299    *
 300    * @access public
 301    *
 302    * @return void
 303    *
 304    */
 305   function preProcess() {}
 306
 307   /**
 308    * This function is called after the form is validated. Any
 309    * processing of form state etc should be done in this function.
 310    * Typically all processing associated with a form should be done
 311    * here and relevant state should be stored in the session
 312    *
 313    * This is a virtual function and should be redefined if needed
 314    *
 315    * @access public
 316    *
 317    * @return void
 318    *
 319    */
 320   function postProcess() {}
 321
 322   /**
 323    * This function is just a wrapper, so that we can call all the hook functions
 324    * @param bool $allowAjax - FIXME: This feels kind of hackish, ideally we would take the json-related code from this function
 325    *                          and bury it deeper down in the controller
 326    */
 327   function mainProcess($allowAjax = TRUE) {
 328     $this->postProcess();
 329     $this->postProcessHook();
 330
 331     // Respond with JSON if in AJAX context (also support legacy value '6')
 332     if ($allowAjax && !empty($_REQUEST['snippet']) && in_array($_REQUEST['snippet'], array(CRM_Core_Smarty::PRINT_JSON, 6))) {
 333       $this->ajaxResponse['buttonName'] = str_replace('_qf_' . $this->getAttribute('id') . '_', '', $this->controller->getButtonName());
 334       $this->ajaxResponse['action'] = $this->_action;
 335       if (isset($this->_id) || isset($this->id)) {
 336         $this->ajaxResponse['id'] = isset($this->id) ? $this->id : $this->_id;
 337       }
 338       CRM_Core_Page_AJAX::returnJsonResponse($this->ajaxResponse);
 339     }
 340   }
 341
 342   /**
 343    * The postProcess hook is typically called by the framework
 344    * However in a few cases, the form exits or redirects early in which
 345    * case it needs to call this function so other modules can do the needful
 346    * Calling this function directly should be avoided if possible. In general a
 347    * better way is to do setUserContext so the framework does the redirect
 348    *
 349    */
 350   function postProcessHook() {
 351     CRM_Utils_Hook::postProcess(get_class($this), $this);
 352   }
 353
 354   /**
 355    * This virtual function is used to build the form. It replaces the
 356    * buildForm associated with QuickForm_Page. This allows us to put
 357    * preProcess in front of the actual form building routine
 358    *
 359    * @access public
 360    *
 361    * @return void
 362    *
 363    */
 364   function buildQuickForm() {}
 365
 366   /**
 367    * This virtual function is used to set the default values of
 368    * various form elements
 369    *
 370    * access        public
 371    *
 372    * @return array reference to the array of default values
 373    *
 374    */
 375   function setDefaultValues() {}
 376
 377   /**
 378    * This is a virtual function that adds group and global rules to
 379    * the form. Keeping it distinct from the form to keep code small
 380    * and localized in the form building code
 381    *
 382    * @access public
 383    *
 384    * @return void
 385    *
 386    */
 387   function addRules() {}
 388
 389   /**
 390    * Performs the server side validation
 391    * @access    public
 392    * @since     1.0
 393    * @return    boolean   true if no error found
 394    * @throws    HTML_QuickForm_Error
 395    */
 396   function validate() {
 397     $error = parent::validate();
 398
 399     $this->validateChainSelectFields();
 400
 401     $hookErrors = CRM_Utils_Hook::validate(
 402       get_class($this),
 403       $this->_submitValues,
 404       $this->_submitFiles,
 405       $this
 406     );
 407
 408     if (!is_array($hookErrors)) {
 409       $hookErrors = array();
 410     }
 411
 412     CRM_Utils_Hook::validateForm(
 413       get_class($this),
 414       $this->_submitValues,
 415       $this->_submitFiles,
 416       $this,
 417       $hookErrors
 418     );
 419
 420     if (!empty($hookErrors)) {
 421       $this->_errors += $hookErrors;
 422     }
 423
 424     return (0 == count($this->_errors));
 425   }
 426
 427   /**
 428    * Core function that builds the form. We redefine this function
 429    * here and expect all CRM forms to build their form in the function
 430    * buildQuickForm.
 431    *
 432    */
 433   function buildForm() {
 434     $this->_formBuilt = TRUE;
 435
 436     $this->preProcess();
 437
 438     $this->assign('translatePermission', CRM_Core_Permission::check('translate CiviCRM'));
 439
 440     if (
 441       $this->controller->_key &&
 442       $this->controller->_generateQFKey
 443     ) {
 444       $this->addElement('hidden', 'qfKey', $this->controller->_key);
 445       $this->assign('qfKey', $this->controller->_key);
 446
 447     }
 448
 449     // _generateQFKey suppresses the qfKey generation on form snippets that
 450     // are part of other forms, hence we use that to avoid adding entryURL
 451     if ($this->controller->_generateQFKey && $this->controller->_entryURL) {
 452       $this->addElement('hidden', 'entryURL', $this->controller->_entryURL);
 453     }
 454
 455     $this->buildQuickForm();
 456
 457     $defaults = $this->setDefaultValues();
 458     unset($defaults['qfKey']);
 459
 460     if (!empty($defaults)) {
 461       $this->setDefaults($defaults);
 462     }
 463
 464     // call the form hook
 465     // also call the hook function so any modules can set thier own custom defaults
 466     // the user can do both the form and set default values with this hook
 467     CRM_Utils_Hook::buildForm(get_class($this), $this);
 468
 469     $this->addRules();
 470
 471     //Set html data-attribute to enable warning user of unsaved changes
 472     if ($this->unsavedChangesWarn === true
 473         || (!isset($this->unsavedChangesWarn)
 474            && ($this->_action & CRM_Core_Action::ADD || $this->_action & CRM_Core_Action::UPDATE)
 475            )
 476         ) {
 477           $this->setAttribute('data-warn-changes', 'true');
 478     }
 479   }
 480
 481   /**
 482    * Add default Next / Back buttons
 483    *
 484    * @param array   array of associative arrays in the order in which the buttons should be
 485    *                displayed. The associate array has 3 fields: 'type', 'name' and 'isDefault'
 486    *                The base form class will define a bunch of static arrays for commonly used
 487    *                formats
 488    *
 489    * @return void
 490    *
 491    * @access public
 492    *
 493    */
 494   function addButtons($params) {
 495     $prevnext = array();
 496     $spacing = array();
 497     foreach ($params as $button) {
 498       $js = CRM_Utils_Array::value('js', $button);
 499       $isDefault = CRM_Utils_Array::value('isDefault', $button, FALSE);
 500       if ($isDefault) {
 501         $attrs = array('class' => 'crm-form-submit default');
 502       }
 503       else {
 504         $attrs = array('class' => 'crm-form-submit');
 505       }
 506
 507       if ($js) {
 508         $attrs = array_merge($js, $attrs);
 509       }
 510
 511       if ($button['type'] === 'cancel') {
 512         $attrs['class'] .= ' cancel';
 513       }
 514
 515       if ($button['type'] === 'reset') {
 516         $prevnext[] = $this->createElement($button['type'], 'reset', $button['name'], $attrs);
 517       }
 518       else {
 519         if (!empty($button['subName'])) {
 520           $buttonName = $this->getButtonName($button['type'], $button['subName']);
 521         }
 522         else {
 523           $buttonName = $this->getButtonName($button['type']);
 524         }
 525
 526         if (in_array($button['type'], array('next', 'upload', 'done')) && $button['name'] === ts('Save')) {
 527           $attrs = array_merge($attrs, (array('accesskey' => 'S')));
 528         }
 529         $prevnext[] = $this->createElement('submit', $buttonName, $button['name'], $attrs);
 530       }
 531       if (!empty($button['isDefault'])) {
 532         $this->setDefaultAction($button['type']);
 533       }
 534
 535       // if button type is upload, set the enctype
 536       if ($button['type'] == 'upload') {
 537         $this->updateAttributes(array('enctype' => 'multipart/form-data'));
 538         $this->setMaxFileSize();
 539       }
 540
 541       // hack - addGroup uses an array to express variable spacing, read from the last element
 542       $spacing[] = CRM_Utils_Array::value('spacing', $button, self::ATTR_SPACING);
 543     }
 544     $this->addGroup($prevnext, 'buttons', '', $spacing, FALSE);
 545   }
 546
 547   /**
 548    * getter function for Name
 549    *
 550    * @return string
 551    * @access public
 552    */
 553   function getName() {
 554     return $this->_name;
 555   }
 556
 557   /**
 558    * getter function for State
 559    *
 560    * @return object
 561    * @access public
 562    */
 563   function &getState() {
 564     return $this->_state;
 565   }
 566
 567   /**
 568    * getter function for StateType
 569    *
 570    * @return int
 571    * @access public
 572    */
 573   function getStateType() {
 574     return $this->_state->getType();
 575   }
 576
 577   /**
 578    * getter function for title. Should be over-ridden by derived class
 579    *
 580    * @return string
 581    * @access public
 582    */
 583   function getTitle() {
 584     return $this->_title ? $this->_title : ts('ERROR: Title is not Set');
 585   }
 586
 587   /**
 588    * setter function for title.
 589    *
 590    * @param string $title the title of the form
 591    *
 592    * @return void
 593    * @access public
 594    */
 595   function setTitle($title) {
 596     $this->_title = $title;
 597   }
 598
 599   /**
 600    * Setter function for options
 601    *
 602    * @param mixed
 603    *
 604    * @return void
 605    * @access public
 606    */
 607   function setOptions($options) {
 608     $this->_options = $options;
 609   }
 610
 611   /**
 612    * getter function for link.
 613    *
 614    * @return string
 615    * @access public
 616    */
 617   function getLink() {
 618     $config = CRM_Core_Config::singleton();
 619     return CRM_Utils_System::url($_GET[$config->userFrameworkURLVar],
 620       '_qf_' . $this->_name . '_display=true'
 621     );
 622   }
 623
 624   /**
 625    * boolean function to determine if this is a one form page
 626    *
 627    * @return boolean
 628    * @access public
 629    */
 630   function isSimpleForm() {
 631     return $this->_state->getType() & (CRM_Core_State::START | CRM_Core_State::FINISH);
 632   }
 633
 634   /**
 635    * getter function for Form Action
 636    *
 637    * @return string
 638    * @access public
 639    */
 640   function getFormAction() {
 641     return $this->_attributes['action'];
 642   }
 643
 644   /**
 645    * setter function for Form Action
 646    *
 647    * @param string
 648    *
 649    * @return void
 650    * @access public
 651    */
 652   function setFormAction($action) {
 653     $this->_attributes['action'] = $action;
 654   }
 655
 656   /**
 657    * render form and return contents
 658    *
 659    * @return string
 660    * @access public
 661    */
 662   function toSmarty() {
 663     $this->preProcessChainSelectFields();
 664     $renderer = $this->getRenderer();
 665     $this->accept($renderer);
 666     $content = $renderer->toArray();
 667     $content['formName'] = $this->getName();
 668     // CRM-15153
 669     $content['formClass'] = CRM_Utils_System::getClassName($this);
 670     return $content;
 671   }
 672
 673   /**
 674    * getter function for renderer. If renderer is not set
 675    * create one and initialize it
 676    *
 677    * @return object
 678    * @access public
 679    */
 680   function &getRenderer() {
 681     if (!isset($this->_renderer)) {
 682       $this->_renderer = CRM_Core_Form_Renderer::singleton();
 683     }
 684     return $this->_renderer;
 685   }
 686
 687   /**
 688    * Use the form name to create the tpl file name
 689    *
 690    * @return string
 691    * @access public
 692    */
 693   function getTemplateFileName() {
 694     $ext = CRM_Extension_System::singleton()->getMapper();
 695     if ($ext->isExtensionClass(CRM_Utils_System::getClassName($this))) {
 696       $filename = $ext->getTemplateName(CRM_Utils_System::getClassName($this));
 697       $tplname = $ext->getTemplatePath(CRM_Utils_System::getClassName($this)) . DIRECTORY_SEPARATOR . $filename;
 698     }
 699     else {
 700       $tplname = str_replace('_',
 701         DIRECTORY_SEPARATOR,
 702         CRM_Utils_System::getClassName($this)
 703       ) . '.tpl';
 704     }
 705     return $tplname;
 706   }
 707
 708   /**
 709    * A wrapper for getTemplateFileName that includes calling the hook to
 710    * prevent us from having to copy & paste the logic of calling the hook
 711    */
 712   function getHookedTemplateFileName() {
 713     $pageTemplateFile = $this->getTemplateFileName();
 714     CRM_Utils_Hook::alterTemplateFile(get_class($this), $this, 'page', $pageTemplateFile);
 715     return $pageTemplateFile;
 716   }
 717
 718   /**
 719    * Default extra tpl file basically just replaces .tpl with .extra.tpl
 720    * i.e. we dont override
 721    *
 722    * @return string
 723    * @access public
 724    */
 725   function overrideExtraTemplateFileName() {
 726     return NULL;
 727   }
 728
 729   /**
 730    * Error reporting mechanism
 731    *
 732    * @param string  $message Error Message
 733    * @param int     $code    Error Code
 734    * @param CRM_Core_DAO $dao     A data access object on which we perform a rollback if non - empty
 735    *
 736    * @return void
 737    * @access public
 738    */
 739   function error($message, $code = NULL, $dao = NULL) {
 740     if ($dao) {
 741       $dao->query('ROLLBACK');
 742     }
 743
 744     $error = CRM_Core_Error::singleton();
 745
 746     $error->push($code, $message);
 747   }
 748
 749   /**
 750    * Store the variable with the value in the form scope
 751    *
 752    * @param  string name  : name  of the variable
 753    * @param  mixed  value : value of the variable
 754    *
 755    * @access public
 756    *
 757    * @return void
 758    *
 759    */
 760   function set($name, $value) {
 761     $this->controller->set($name, $value);
 762   }
 763
 764   /**
 765    * Get the variable from the form scope
 766    *
 767    * @param  string name  : name  of the variable
 768    *
 769    * @access public
 770    *
 771    * @return mixed
 772    *
 773    */
 774   function get($name) {
 775     return $this->controller->get($name);
 776   }
 777
 778   /**
 779    * getter for action
 780    *
 781    * @return int
 782    * @access public
 783    */
 784   function getAction() {
 785     return $this->_action;
 786   }
 787
 788   /**
 789    * setter for action
 790    *
 791    * @param  int  $action the mode we want to set the form
 792    *
 793    * @return void
 794    * @access public
 795    */
 796   function setAction($action) {
 797     $this->_action = $action;
 798   }
 799
 800   /**
 801    * assign value to name in template
 802    *
 803    * @param $var
 804    * @param mixed $value value of varaible
 805    *
 806    * @internal param array|string $name name  of variable
 807    * @return void
 808    * @access public
 809    */
 810   function assign($var, $value = NULL) {
 811     self::$_template->assign($var, $value);
 812   }
 813
 814   /**
 815    * assign value to name in template by reference
 816    *
 817    * @param $var
 818    * @param mixed $value value of varaible
 819    *
 820    * @internal param array|string $name name  of variable
 821    * @return void
 822    * @access public
 823    */
 824   function assign_by_ref($var, &$value) {
 825     self::$_template->assign_by_ref($var, $value);
 826   }
 827
 828   /**
 829    * appends values to template variables
 830    *
 831    * @param array|string $tpl_var the template variable name(s)
 832    * @param mixed $value the value to append
 833    * @param bool $merge
 834    */
 835   function append($tpl_var, $value=NULL, $merge=FALSE) {
 836     self::$_template->append($tpl_var, $value, $merge);
 837   }
 838
 839   /**
 840    * Returns an array containing template variables
 841    *
 842    * @param string $name
 843    *
 844    * @internal param string $type
 845    * @return array
 846    */
 847   function get_template_vars($name=null) {
 848     return self::$_template->get_template_vars($name);
 849   }
 850
 851   /**
 852    * @param $name
 853    * @param $title
 854    * @param $values
 855    * @param array $attributes
 856    * @param null $separator
 857    * @param bool $required
 858    *
 859    * @return HTML_QuickForm_group
 860    */
 861   function &addRadio($name, $title, $values, $attributes = array(), $separator = NULL, $required = FALSE) {
 862     $options = array();
 863     $attributes = $attributes ? $attributes : array();
 864     $allowClear = !empty($attributes['allowClear']);
 865     unset($attributes['allowClear']);
 866     $attributes += array('id_suffix' => $name);
 867     foreach ($values as $key => $var) {
 868       $options[] = $this->createElement('radio', NULL, NULL, $var, $key, $attributes);
 869     }
 870     $group = $this->addGroup($options, $name, $title, $separator);
 871     if ($required) {
 872       $this->addRule($name, ts('%1 is a required field.', array(1 => $title)), 'required');
 873     }
 874     if ($allowClear) {
 875       $group->setAttribute('allowClear', TRUE);
 876     }
 877     return $group;
 878   }
 879
 880   /**
 881    * @param $id
 882    * @param $title
 883    * @param bool $allowClear
 884    * @param null $required
 885    * @param array $attributes
 886    */
 887   function addYesNo($id, $title, $allowClear = FALSE, $required = NULL, $attributes = array()) {
 888     $attributes += array('id_suffix' => $id);
 889     $choice   = array();
 890     $choice[] = $this->createElement('radio', NULL, '11', ts('Yes'), '1', $attributes);
 891     $choice[] = $this->createElement('radio', NULL, '11', ts('No'), '0', $attributes);
 892
 893     $group = $this->addGroup($choice, $id, $title);
 894     if ($allowClear) {
 895       $group->setAttribute('allowClear', TRUE);
 896     }
 897     if ($required) {
 898       $this->addRule($id, ts('%1 is a required field.', array(1 => $title)), 'required');
 899     }
 900   }
 901
 902   /**
 903    * @param $id
 904    * @param $title
 905    * @param $values
 906    * @param null $other
 907    * @param null $attributes
 908    * @param null $required
 909    * @param null $javascriptMethod
 910    * @param string $separator
 911    * @param bool $flipValues
 912    */
 913   function addCheckBox($id, $title, $values, $other = NULL,
 914     $attributes       = NULL, $required = NULL,
 915     $javascriptMethod = NULL,
 916     $separator        = '<br />', $flipValues = FALSE
 917   ) {
 918     $options = array();
 919
 920     if ($javascriptMethod) {
 921       foreach ($values as $key => $var) {
 922         if (!$flipValues) {
 923           $options[] = $this->createElement('checkbox', $var, NULL, $key, $javascriptMethod);
 924         }
 925         else {
 926           $options[] = $this->createElement('checkbox', $key, NULL, $var, $javascriptMethod);
 927         }
 928       }
 929     }
 930     else {
 931       foreach ($values as $key => $var) {
 932         if (!$flipValues) {
 933           $options[] = $this->createElement('checkbox', $var, NULL, $key);
 934         }
 935         else {
 936           $options[] = $this->createElement('checkbox', $key, NULL, $var);
 937         }
 938       }
 939     }
 940
 941     $this->addGroup($options, $id, $title, $separator);
 942
 943     if ($other) {
 944       $this->addElement('text', $id . '_other', ts('Other'), $attributes[$id . '_other']);
 945     }
 946
 947     if ($required) {
 948       $this->addRule($id,
 949         ts('%1 is a required field.', array(1 => $title)),
 950         'required'
 951       );
 952     }
 953   }
 954
 955   function resetValues() {
 956     $data = $this->controller->container();
 957     $data['values'][$this->_name] = array();
 958   }
 959
 960   /**
 961    * simple shell that derived classes can call to add buttons to
 962    * the form with a customized title for the main Submit
 963    *
 964    * @param string $title title of the main button
 965    * @param string $nextType
 966    * @param string $backType
 967    * @param bool|string $submitOnce If true, add javascript to next button submit which prevents it from being clicked more than once
 968    *
 969    * @internal param string $type button type for the form after processing
 970    * @return void
 971    * @access public
 972    */
 973   function addDefaultButtons($title, $nextType = 'next', $backType = 'back', $submitOnce = FALSE) {
 974     $buttons = array();
 975     if ($backType != NULL) {
 976       $buttons[] = array(
 977         'type' => $backType,
 978         'name' => ts('Previous'),
 979       );
 980     }
 981     if ($nextType != NULL) {
 982       $nextButton = array(
 983         'type' => $nextType,
 984         'name' => $title,
 985         'isDefault' => TRUE,
 986       );
 987       if ($submitOnce) {
 988         $nextButton['js'] = array('onclick' => "return submitOnce(this,'{$this->_name}','" . ts('Processing') . "');");
 989       }
 990       $buttons[] = $nextButton;
 991     }
 992     $this->addButtons($buttons);
 993   }
 994
 995   /**
 996    * @param $name
 997    * @param string $from
 998    * @param string $to
 999    * @param string $label
1000    * @param string $dateFormat
1001    * @param bool $required
1002    * @param bool $displayTime
1003    */
1004   function addDateRange($name, $from = '_from', $to = '_to', $label = 'From:', $dateFormat = 'searchDate', $required = FALSE, $displayTime = FALSE) {
1005     if ($displayTime) {
1006       $this->addDateTime($name . $from, $label, $required, array('formatType' => $dateFormat));
1007       $this->addDateTime($name . $to, ts('To:'), $required, array('formatType' => $dateFormat));
1008     } else {
1009       $this->addDate($name . $from, $label, $required, array('formatType' => $dateFormat));
1010       $this->addDate($name . $to, ts('To:'), $required, array('formatType' => $dateFormat));
1011     }
1012   }
1013
1014   /**
1015    * Adds a select based on field metadata
1016    * TODO: This could be even more generic and widget type (select in this case) could also be read from metadata
1017    * Perhaps a method like $form->bind($name) which would look up all metadata for named field
1018    * @param $name - field name to go on the form
1019    * @param array $props - mix of html attributes and special properties, namely
1020    *   - entity (api entity name, can usually be inferred automatically from the form class)
1021    *   - field (field name - only needed if different from name used on the form)
1022    *   - option_url - path to edit this option list - usually retrieved automatically - set to NULL to disable link
1023    *   - placeholder - set to NULL to disable
1024    *   - multiple - bool
1025    * @param bool $required
1026    * @throws CRM_Core_Exception
1027    * @return HTML_QuickForm_Element
1028    */
1029   function addSelect($name, $props = array(), $required = FALSE) {
1030     if (!isset($props['entity'])) {
1031       $props['entity'] = CRM_Utils_Api::getEntityName($this);
1032     }
1033     if (!isset($props['field'])) {
1034       $props['field'] = strrpos($name, '[') ? rtrim(substr($name, 1 + strrpos($name, '[')), ']') : $name;
1035     }
1036     $info = civicrm_api3($props['entity'], 'getoptions', array(
1037         'field' => $props['field'],
1038         'options' => array('metadata' => array('fields'))
1039       )
1040     );
1041     $options = $info['values'];
1042     if (!array_key_exists('placeholder', $props)) {
1043       $props['placeholder'] = $required ? ts('- select -') : ts('- none -');
1044     }
1045     // Handle custom field
1046     if (strpos($name, 'custom_') === 0 && is_numeric($name[7])) {
1047       list(, $id) = explode('_', $name);
1048       $label = isset($props['label']) ? $props['label'] : CRM_Core_DAO::getFieldValue('CRM_Core_DAO_CustomField', 'label', $id);
1049       $gid = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_CustomField', 'option_group_id', $id);
1050       $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);
1051     }
1052     // Core field
1053     else {
1054       foreach($info['metadata']['fields'] as $uniqueName => $fieldSpec) {
1055         if (
1056           $uniqueName === $props['field'] ||
1057           CRM_Utils_Array::value('name', $fieldSpec) === $props['field'] ||
1058           in_array($props['field'], CRM_Utils_Array::value('api.aliases', $fieldSpec, array()))
1059         ) {
1060           break;
1061         }
1062       }
1063       $label = isset($props['label']) ? $props['label'] : $fieldSpec['title'];
1064       $props['data-option-edit-path'] = array_key_exists('option_url', $props) ? $props['option_url'] : $props['data-option-edit-path'] = CRM_Core_PseudoConstant::getOptionEditUrl($fieldSpec);
1065     }
1066     $props['class'] = (isset($props['class']) ? $props['class'] . ' ' : '') . "crm-select2";
1067     $props['data-api-entity'] = $props['entity'];
1068     $props['data-api-field'] = $props['field'];
1069     CRM_Utils_Array::remove($props, 'label', 'entity', 'field', 'option_url');
1070     return $this->add('select', $name, $label, $options, $required, $props);
1071   }
1072
1073   /**
1074    * Add a widget for selecting/editing/creating/copying a profile form
1075    *
1076    * @param string $name HTML form-element name
1077    * @param string $label Printable label
1078    * @param string $allowCoreTypes only present a UFGroup if its group_type includes a subset of $allowCoreTypes; e.g. 'Individual', 'Activity'
1079    * @param string $allowSubTypes only present a UFGroup if its group_type is compatible with $allowSubypes
1080    * @param array $entities
1081    * @param bool $default //CRM-15427
1082    */
1083   function addProfileSelector($name, $label, $allowCoreTypes, $allowSubTypes, $entities, $default = FALSE) {
1084     // Output widget
1085     // FIXME: Instead of adhoc serialization, use a single json_encode()
1086     CRM_UF_Page_ProfileEditor::registerProfileScripts();
1087     CRM_UF_Page_ProfileEditor::registerSchemas(CRM_Utils_Array::collect('entity_type', $entities));
1088     $this->add('text', $name, $label, array(
1089       'class' => 'crm-profile-selector',
1090       // Note: client treats ';;' as equivalent to \0, and ';;' works better in HTML
1091       'data-group-type' => CRM_Core_BAO_UFGroup::encodeGroupType($allowCoreTypes, $allowSubTypes, ';;'),
1092       'data-entities' => json_encode($entities),
1093       //CRM-15427
1094       'data-default' => $default,
1095     ));
1096   }
1097
1098   /**
1099    * @param $name
1100    * @param $label
1101    * @param $attributes
1102    * @param bool $forceTextarea
1103    */
1104   function addWysiwyg($name, $label, $attributes, $forceTextarea = FALSE) {
1105     // 1. Get configuration option for editor (tinymce, ckeditor, pure textarea)
1106     // 2. Based on the option, initialise proper editor
1107     $editorID = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME,
1108       'editor_id'
1109     );
1110     $editor = strtolower(CRM_Utils_Array::value($editorID,
1111         CRM_Core_OptionGroup::values('wysiwyg_editor')
1112       ));
1113     if (!$editor || $forceTextarea) {
1114       $editor = 'textarea';
1115     }
1116     if ($editor == 'joomla default editor') {
1117       $editor = 'joomlaeditor';
1118     }
1119
1120     if ($editor == 'drupal default editor') {
1121       $editor = 'drupalwysiwyg';
1122     }
1123
1124     //lets add the editor as a attribute
1125     $attributes['editor'] = $editor;
1126
1127     $this->addElement($editor, $name, $label, $attributes);
1128     $this->assign('editor', $editor);
1129
1130     // include wysiwyg editor js files
1131     // FIXME: This code does not make any sense
1132     $includeWysiwygEditor = FALSE;
1133     $includeWysiwygEditor = $this->get('includeWysiwygEditor');
1134     if (!$includeWysiwygEditor) {
1135       $includeWysiwygEditor = TRUE;
1136       $this->set('includeWysiwygEditor', $includeWysiwygEditor);
1137     }
1138
1139     $this->assign('includeWysiwygEditor', $includeWysiwygEditor);
1140   }
1141
1142   /**
1143    * @param $id
1144    * @param $title
1145    * @param null $required
1146    * @param null $extra
1147    */
1148   function addCountry($id, $title, $required = NULL, $extra = NULL) {
1149     $this->addElement('select', $id, $title,
1150       array(
1151         '' => ts('- select -')) + CRM_Core_PseudoConstant::country(), $extra
1152     );
1153     if ($required) {
1154       $this->addRule($id, ts('Please select %1', array(1 => $title)), 'required');
1155     }
1156   }
1157
1158   /**
1159    * @param $name
1160    * @param $label
1161    * @param $options
1162    * @param $attributes
1163    * @param null $required
1164    * @param null $javascriptMethod
1165    */
1166   function addSelectOther($name, $label, $options, $attributes, $required = NULL, $javascriptMethod = NULL) {
1167
1168     $this->addElement('select', $name . '_id', $label, $options, $javascriptMethod);
1169
1170     if ($required) {
1171       $this->addRule($name . '_id', ts('Please select %1', array(1 => $label)), 'required');
1172     }
1173   }
1174
1175   /**
1176    * @return null
1177    */
1178   public function getRootTitle() {
1179     return NULL;
1180   }
1181
1182   /**
1183    * @return string
1184    */
1185   public function getCompleteTitle() {
1186     return $this->getRootTitle() . $this->getTitle();
1187   }
1188
1189   /**
1190    * @return CRM_Core_Smarty
1191    */
1192   static function &getTemplate() {
1193     return self::$_template;
1194   }
1195
1196   /**
1197    * @param $elementName
1198    */
1199   function addUploadElement($elementName) {
1200     $uploadNames = $this->get('uploadNames');
1201     if (!$uploadNames) {
1202       $uploadNames = array();
1203     }
1204     if (is_array($elementName)) {
1205       foreach ($elementName as $name) {
1206         if (!in_array($name, $uploadNames)) {
1207           $uploadNames[] = $name;
1208         }
1209       }
1210     }
1211     else {
1212       if (!in_array($elementName, $uploadNames)) {
1213         $uploadNames[] = $elementName;
1214       }
1215     }
1216     $this->set('uploadNames', $uploadNames);
1217
1218     $config = CRM_Core_Config::singleton();
1219     if (!empty($uploadNames)) {
1220       $this->controller->addUploadAction($config->customFileUploadDir, $uploadNames);
1221     }
1222   }
1223
1224   /**
1225    * @return string
1226    */
1227   function buttonType() {
1228     $uploadNames = $this->get('uploadNames');
1229     $buttonType = (is_array($uploadNames) && !empty($uploadNames)) ? 'upload' : 'next';
1230     $this->assign('buttonType', $buttonType);
1231     return $buttonType;
1232   }
1233
1234   /**
1235    * @param $name
1236    *
1237    * @return null
1238    */
1239   function getVar($name) {
1240     return isset($this->$name) ? $this->$name : NULL;
1241   }
1242
1243   /**
1244    * @param $name
1245    * @param $value
1246    */
1247   function setVar($name, $value) {
1248     $this->$name = $value;
1249   }
1250
1251   /**
1252    *  Function to add date
1253    *  @param string $name   name of the element
1254    *  @param string $label  label of the element
1255    *  @param array  $attributes key / value pair
1256    *
1257    // if you need time
1258    *  $attributes = array ( 'addTime' => true,
1259    *                        'formatType' => 'relative' or 'birth' etc check advanced date settings
1260    *                      );
1261    *  @param boolean $required  true if required
1262    *
1263    */
1264   function addDate($name, $label, $required = FALSE, $attributes = NULL) {
1265     if (!empty($attributes['formatType'])) {
1266       // get actual format
1267       $params = array('name' => $attributes['formatType']);
1268       $values = array();
1269
1270       // cache date information
1271       static $dateFormat;
1272       $key = "dateFormat_" . str_replace(' ', '_', $attributes['formatType']);
1273       if (empty($dateFormat[$key])) {
1274         CRM_Core_DAO::commonRetrieve('CRM_Core_DAO_PreferencesDate', $params, $values);
1275         $dateFormat[$key] = $values;
1276       }
1277       else {
1278         $values = $dateFormat[$key];
1279       }
1280
1281       if ($values['date_format']) {
1282         $attributes['format'] = $values['date_format'];
1283       }
1284
1285       if (!empty($values['time_format'])) {
1286         $attributes['timeFormat'] = $values['time_format'];
1287       }
1288       $attributes['startOffset'] = $values['start'];
1289       $attributes['endOffset'] = $values['end'];
1290     }
1291
1292     $config = CRM_Core_Config::singleton();
1293     if (empty($attributes['format'])) {
1294       $attributes['format'] = $config->dateInputFormat;
1295     }
1296
1297     if (!isset($attributes['startOffset'])) {
1298       $attributes['startOffset'] = 10;
1299     }
1300
1301     if (!isset($attributes['endOffset'])) {
1302       $attributes['endOffset'] = 10;
1303     }
1304
1305     $this->add('text', $name, $label, $attributes);
1306
1307     if (!empty($attributes['addTime']) || !empty($attributes['timeFormat'])) {
1308
1309       if (!isset($attributes['timeFormat'])) {
1310         $timeFormat = $config->timeInputFormat;
1311       }
1312       else {
1313         $timeFormat = $attributes['timeFormat'];
1314       }
1315
1316       // 1 - 12 hours and 2 - 24 hours, but for jquery widget it is 0 and 1 respectively
1317       if ($timeFormat) {
1318         $show24Hours = TRUE;
1319         if ($timeFormat == 1) {
1320           $show24Hours = FALSE;
1321         }
1322
1323         //CRM-6664 -we are having time element name
1324         //in either flat string or an array format.
1325         $elementName = $name . '_time';
1326         if (substr($name, -1) == ']') {
1327           $elementName = substr($name, 0, strlen($name) - 1) . '_time]';
1328         }
1329
1330         $this->add('text', $elementName, ts('Time'), array('timeFormat' => $show24Hours));
1331       }
1332     }
1333
1334     if ($required) {
1335       $this->addRule($name, ts('Please select %1', array(1 => $label)), 'required');
1336       if (!empty($attributes['addTime']) && !empty($attributes['addTimeRequired'])) {
1337         $this->addRule($elementName, ts('Please enter a time.'), 'required');
1338       }
1339     }
1340   }
1341
1342   /**
1343    *  Function that will add date and time
1344    */
1345   function addDateTime($name, $label, $required = FALSE, $attributes = NULL) {
1346     $addTime = array('addTime' => TRUE);
1347     if (is_array($attributes)) {
1348       $attributes = array_merge($attributes, $addTime);
1349     }
1350     else {
1351       $attributes = $addTime;
1352     }
1353
1354     $this->addDate($name, $label, $required, $attributes);
1355   }
1356
1357   /**
1358    * add a currency and money element to the form
1359    */
1360   function addMoney($name,
1361     $label,
1362     $required        = FALSE,
1363     $attributes      = NULL,
1364     $addCurrency     = TRUE,
1365     $currencyName    = 'currency',
1366     $defaultCurrency = NULL,
1367     $freezeCurrency  = FALSE
1368   ) {
1369     $element = $this->add('text', $name, $label, $attributes, $required);
1370     $this->addRule($name, ts('Please enter a valid amount.'), 'money');
1371
1372     if ($addCurrency) {
1373       $ele = $this->addCurrency($currencyName, NULL, TRUE, $defaultCurrency, $freezeCurrency);
1374     }
1375
1376     return $element;
1377   }
1378
1379   /**
1380    * add currency element to the form
1381    */
1382   function addCurrency($name = 'currency',
1383     $label           = NULL,
1384     $required        = TRUE,
1385     $defaultCurrency = NULL,
1386     $freezeCurrency  = FALSE
1387   ) {
1388     $currencies = CRM_Core_OptionGroup::values('currencies_enabled');
1389     $options = array('class' => 'crm-select2 eight');
1390     if (!$required) {
1391       $currencies = array('' => '') + $currencies;
1392       $options['placeholder'] = ts('- none -');
1393     }
1394     $ele = $this->add('select', $name, $label, $currencies, $required, $options);
1395     if ($freezeCurrency) {
1396       $ele->freeze();
1397     }
1398     if (!$defaultCurrency) {
1399       $config = CRM_Core_Config::singleton();
1400       $defaultCurrency = $config->defaultCurrency;
1401     }
1402     $this->setDefaults(array($name => $defaultCurrency));
1403   }
1404
1405   /**
1406    * Create a single or multiple entity ref field
1407    * @param string $name
1408    * @param string $label
1409    * @param array $props mix of html and widget properties, including:
1410    *  - select - params to give to select2 widget
1411    *  - entity - defaults to contact
1412    *  - create - can the user create a new entity on-the-fly?
1413    *             Set to TRUE if entity is contact and you want the default profiles,
1414    *             or pass in your own set of links. @see CRM_Core_BAO_UFGroup::getCreateLinks for format
1415    *             note that permissions are checked automatically
1416    *  - api - array of settings for the getlist api wrapper
1417    *          note that it accepts a 'params' setting which will be passed to the underlying api
1418    *  - placeholder - string
1419    *  - multiple - bool
1420    *  - class, etc. - other html properties
1421    * @param bool $required
1422    *
1423    * @access public
1424    * @return HTML_QuickForm_Element
1425    */
1426   function addEntityRef($name, $label = '', $props = array(), $required = FALSE) {
1427     require_once "api/api.php";
1428     $config = CRM_Core_Config::singleton();
1429     // Default properties
1430     $props['api'] = CRM_Utils_Array::value('api', $props, array());
1431     $props['entity'] = _civicrm_api_get_entity_name_from_camel(CRM_Utils_Array::value('entity', $props, 'contact'));
1432     $props['class'] = ltrim(CRM_Utils_Array::value('class', $props, '') . ' crm-form-entityref');
1433
1434     if ($props['entity'] == 'contact' && isset($props['create']) && !(CRM_Core_Permission::check('edit all contacts') || CRM_Core_Permission::check('add contacts'))) {
1435       unset($props['create']);
1436     }
1437
1438     $props['placeholder'] = CRM_Utils_Array::value('placeholder', $props, $required ? ts('- select %1 -', array(1 => ts(str_replace('_', ' ', $props['entity'])))) : ts('- none -'));
1439
1440     $defaults = array();
1441     if (!empty($props['multiple'])) {
1442       $defaults['multiple'] = TRUE;
1443     }
1444     $props['select'] = CRM_Utils_Array::value('select', $props, array()) + $defaults;
1445
1446     $this->formatReferenceFieldAttributes($props);
1447     return $this->add('text', $name, $label, $props, $required);
1448   }
1449
1450   /**
1451    * @param $props
1452    */
1453   private function formatReferenceFieldAttributes(&$props) {
1454     $props['data-select-params'] = json_encode($props['select']);
1455     $props['data-api-params'] = $props['api'] ? json_encode($props['api']) : NULL;
1456     $props['data-api-entity'] = $props['entity'];
1457     if (!empty($props['create'])) {
1458       $props['data-create-links'] = json_encode($props['create']);
1459     }
1460     CRM_Utils_Array::remove($props, 'multiple', 'select', 'api', 'entity', 'create');
1461   }
1462
1463   /**
1464    * Convert all date fields within the params to mysql date ready for the
1465    * BAO layer. In this case fields are checked against the $_datefields defined for the form
1466    * and if time is defined it is incorporated
1467    *
1468    * @param array $params input params from the form
1469    *
1470    * @todo it would probably be better to work on $this->_params than a passed array
1471    * @todo standardise the format which dates are passed to the BAO layer in & remove date
1472    * handling from BAO
1473    */
1474   function convertDateFieldsToMySQL(&$params){
1475     foreach ($this->_dateFields as $fieldName => $specs){
1476       if(!empty($params[$fieldName])){
1477         $params[$fieldName] = CRM_Utils_Date::isoToMysql(
1478           CRM_Utils_Date::processDate(
1479           $params[$fieldName],
1480           CRM_Utils_Array::value("{$fieldName}_time", $params), TRUE)
1481         );
1482       }
1483       else{
1484         if(isset($specs['default'])){
1485           $params[$fieldName] = date('YmdHis', strtotime($specs['default']));
1486         }
1487       }
1488     }
1489   }
1490
1491   /**
1492    * @param $elementName
1493    */
1494   function removeFileRequiredRules($elementName) {
1495     $this->_required = array_diff($this->_required, array($elementName));
1496     if (isset($this->_rules[$elementName])) {
1497       foreach ($this->_rules[$elementName] as $index => $ruleInfo) {
1498         if ($ruleInfo['type'] == 'uploadedfile') {
1499           unset($this->_rules[$elementName][$index]);
1500         }
1501       }
1502       if (empty($this->_rules[$elementName])) {
1503         unset($this->_rules[$elementName]);
1504       }
1505     }
1506   }
1507
1508   /**
1509    * Function that can be defined in Form to override or
1510    * perform specific action on cancel action
1511    *
1512    * @access public
1513    */
1514   function cancelAction() {}
1515
1516   /**
1517    * Helper function to verify that required fields have been filled
1518    * Typically called within the scope of a FormRule function
1519    */
1520   static function validateMandatoryFields($fields, $values, &$errors) {
1521     foreach ($fields as $name => $fld) {
1522       if (!empty($fld['is_required']) && CRM_Utils_System::isNull(CRM_Utils_Array::value($name, $values))) {
1523         $errors[$name] = ts('%1 is a required field.', array(1 => $fld['title']));
1524       }
1525     }
1526   }
1527
1528   /**
1529    * Get contact if for a form object. Prioritise
1530    *  - cid in URL if 0 (on behalf on someoneelse)
1531    *      (@todo consider setting a variable if onbehalf for clarity of downstream 'if's
1532    *  - logged in user id if it matches the one in the cid in the URL
1533    *  - contact id validated from a checksum from a checksum
1534    *  - cid from the url if the caller has ACL permission to view
1535    *  - fallback is logged in user (or ? NULL if no logged in user) (@todo wouldn't 0 be more intuitive?)
1536    *
1537    * @return mixed NULL|integer
1538    */
1539   function getContactID() {
1540     $tempID = CRM_Utils_Request::retrieve('cid', 'Positive', $this);
1541     if(isset($this->_params) && isset($this->_params['select_contact_id'])) {
1542       $tempID = $this->_params['select_contact_id'];
1543     }
1544     if(isset($this->_params, $this->_params[0]) && !empty($this->_params[0]['select_contact_id'])) {
1545       // event form stores as an indexed array, contribution form not so much...
1546       $tempID = $this->_params[0]['select_contact_id'];
1547     }
1548
1549     // force to ignore the authenticated user
1550     if ($tempID === '0' || $tempID === 0) {
1551       // we set the cid on the form so that this will be retained for the Confirm page
1552       // in the multi-page form & prevent us returning the $userID when this is called
1553       // from that page
1554       // we don't really need to set it when $tempID is set because the params have that stored
1555       $this->set('cid', 0);
1556       return $tempID;
1557     }
1558
1559     $userID = $this->getLoggedInUserContactID();
1560
1561     if ($tempID == $userID) {
1562       return $userID;
1563     }
1564
1565     //check if this is a checksum authentication
1566     $userChecksum = CRM_Utils_Request::retrieve('cs', 'String', $this);
1567     if ($userChecksum) {
1568       //check for anonymous user.
1569       $validUser = CRM_Contact_BAO_Contact_Utils::validChecksum($tempID, $userChecksum);
1570       if ($validUser) {
1571         return $tempID;
1572       }
1573     }
1574     // check if user has permission, CRM-12062
1575     else if ($tempID && CRM_Contact_BAO_Contact_Permission::allow($tempID)) {
1576       return $tempID;
1577     }
1578
1579     return $userID;
1580   }
1581
1582  /**
1583   * Get the contact id of the logged in user
1584   */
1585   function getLoggedInUserContactID() {
1586     // check if the user is logged in and has a contact ID
1587     $session = CRM_Core_Session::singleton();
1588     return $session->get('userID');
1589   }
1590
1591   /**
1592    * add autoselector field -if user has permission to view contacts
1593    * If adding this to a form you also need to add to the tpl e.g
1594    *
1595    * {if !empty($selectable)}
1596    * <div class="crm-summary-row">
1597    *   <div class="crm-label">{$form.select_contact.label}</div>
1598    *   <div class="crm-content">
1599    *     {$form.select_contact.html}
1600    *   </div>
1601    * </div>
1602    * {/if}
1603    *
1604    * @param array $profiles ids of profiles that are on the form (to be autofilled)
1605    * @param array $autoCompleteField
1606    *
1607    * @internal param array $field metadata of field to use as selector including
1608    *  - name_field
1609    *  - id_field
1610    *  - url (for ajax lookup)
1611    *
1612    * @todo add data attributes so we can deal with multiple instances on a form
1613    */
1614   function addAutoSelector($profiles = array(), $autoCompleteField = array()) {
1615     $autoCompleteField = array_merge(array(
1616         'id_field' => 'select_contact_id',
1617         'placeholder' => ts('Select someone else ...'),
1618         'show_hide' => TRUE,
1619         'api' => array('params' => array('contact_type' => 'Individual'))
1620       ), $autoCompleteField);
1621
1622     if($this->canUseAjaxContactLookups()) {
1623       $this->assign('selectable', $autoCompleteField['id_field']);
1624       $this->addEntityRef($autoCompleteField['id_field'], NULL, array('placeholder' => $autoCompleteField['placeholder'], 'api' => $autoCompleteField['api']));
1625
1626       CRM_Core_Resources::singleton()->addScriptFile('civicrm', 'js/AlternateContactSelector.js', 1, 'html-header')
1627       ->addSetting(array(
1628       'form' => array('autocompletes' => $autoCompleteField),
1629       'ids' => array('profile' => $profiles),
1630       ));
1631     }
1632   }
1633
1634   /**
1635    *
1636    */
1637   function canUseAjaxContactLookups() {
1638     if (0 < (civicrm_api3('contact', 'getcount', array('check_permissions' => 1))) &&
1639       CRM_Core_Permission::check(array(array('access AJAX API', 'access CiviCRM')))) {
1640         return TRUE;
1641       }
1642   }
1643
1644   /**
1645    * Add the options appropriate to cid = zero - ie. autocomplete
1646    *
1647    * @todo there is considerable code duplication between the contribution forms & event forms. It is apparent
1648    * that small pieces of duplication are not being refactored into separate functions because their only shared parent
1649    * is this form. Inserting a class FrontEndForm.php between the contribution & event & this class would allow functions like this
1650    * and a dozen other small ones to be refactored into a shared parent with the reduction of much code duplication
1651    */
1652   function addCIDZeroOptions($onlinePaymentProcessorEnabled) {
1653     $this->assign('nocid', TRUE);
1654     $profiles = array();
1655     if($this->_values['custom_pre_id']) {
1656       $profiles[] = $this->_values['custom_pre_id'];
1657     }
1658     if($this->_values['custom_post_id']) {
1659       $profiles[] = $this->_values['custom_post_id'];
1660     }
1661     if($onlinePaymentProcessorEnabled) {
1662       $profiles[] = 'billing';
1663     }
1664     if(!empty($this->_values)) {
1665       $this->addAutoSelector($profiles);
1666     }
1667   }
1668
1669   /**
1670    * Set default values on form for given contact (or no contact defaults)
1671    *
1672    * @param mixed $profile_id (can be id, or profile name)
1673    * @param integer $contactID
1674    *
1675    * @return array
1676    */
1677   function getProfileDefaults($profile_id = 'Billing', $contactID = NULL) {
1678     try{
1679       $defaults = civicrm_api3('profile', 'getsingle', array(
1680         'profile_id' => (array) $profile_id,
1681         'contact_id' => $contactID,
1682       ));
1683       return $defaults;
1684     }
1685     catch (Exception $e) {
1686       // the try catch block gives us silent failure -not 100% sure this is a good idea
1687       // as silent failures are often worse than noisy ones
1688       return array();
1689     }
1690   }
1691
1692   /**
1693    * Sets form attribute
1694    * @see CRM.loadForm
1695    */
1696   function preventAjaxSubmit() {
1697     $this->setAttribute('data-no-ajax-submit', 'true');
1698   }
1699
1700   /**
1701    * Sets form attribute
1702    * @see CRM.loadForm
1703    */
1704   function allowAjaxSubmit() {
1705     $this->removeAttribute('data-no-ajax-submit');
1706   }
1707
1708   /**
1709    * Sets page title based on entity and action
1710    * @param string $entityLabel
1711    */
1712   function setPageTitle($entityLabel) {
1713     switch ($this->_action) {
1714       case CRM_Core_Action::ADD:
1715         CRM_Utils_System::setTitle(ts('New %1', array(1 => $entityLabel)));
1716         break;
1717       case CRM_Core_Action::UPDATE:
1718         CRM_Utils_System::setTitle(ts('Edit %1', array(1 => $entityLabel)));
1719         break;
1720       case CRM_Core_Action::VIEW:
1721       case CRM_Core_Action::PREVIEW:
1722         CRM_Utils_System::setTitle(ts('View %1', array(1 => $entityLabel)));
1723         break;
1724       case CRM_Core_Action::DELETE:
1725         CRM_Utils_System::setTitle(ts('Delete %1', array(1 => $entityLabel)));
1726         break;
1727     }
1728   }
1729
1730   /**
1731    * Create a chain-select target field. All settings are optional; the defaults usually work.
1732    *
1733    * @param string $elementName
1734    * @param array $settings
1735    *
1736    * @return HTML_QuickForm_Element
1737    */
1738   public function addChainSelect($elementName, $settings = array()) {
1739     $props = $settings += array(
1740       'control_field' => str_replace(array('state_province', 'StateProvince', 'county', 'County'), array('country', 'Country', 'state_province', 'StateProvince'), $elementName),
1741       'data-callback' => strpos($elementName, 'rovince') ? 'civicrm/ajax/jqState' : 'civicrm/ajax/jqCounty',
1742       'label' => strpos($elementName, 'rovince') ? ts('State/Province') : ts('County'),
1743       'data-empty-prompt' => strpos($elementName, 'rovince') ? ts('Choose country first') : ts('Choose state first'),
1744       'data-none-prompt' => ts('- N/A -'),
1745       'multiple' => FALSE,
1746       'required' => FALSE,
1747       'placeholder' => empty($settings['required']) ? ts('- none -') : ts('- select -'),
1748     );
1749     CRM_Utils_Array::remove($props, 'label', 'required', 'control_field');
1750     $props['class'] = (empty($props['class']) ? '' : "{$props['class']} ") . 'crm-select2';
1751     $props['data-select-prompt'] = $props['placeholder'];
1752     $props['data-name'] = $elementName;
1753
1754     $this->_chainSelectFields[$settings['control_field']] = $elementName;
1755
1756     // Passing NULL instead of an array of options
1757     // CRM-15225 - normally QF will reject any selected values that are not part of the field's options, but due to a
1758     // quirk in our patched version of HTML_QuickForm_select, this doesn't happen if the options are NULL
1759     // which seems a bit dirty but it allows our dynamically-popuplated select element to function as expected.
1760     return $this->add('select', $elementName, $settings['label'], NULL, $settings['required'], $props);
1761   }
1762
1763   /**
1764    * Set options and attributes for chain select fields based on the controlling field's value
1765    */
1766   private function preProcessChainSelectFields() {
1767     foreach ($this->_chainSelectFields as $control => $target) {
1768       $targetField = $this->getElement($target);
1769       $targetType = $targetField->getAttribute('data-callback') == 'civicrm/ajax/jqCounty' ? 'county' : 'stateProvince';
1770       $options = array();
1771       // If the control field is on the form, setup chain-select and dynamically populate options
1772       if ($this->elementExists($control)) {
1773         $controlField = $this->getElement($control);
1774         $controlType = $targetType == 'county' ? 'stateProvince' : 'country';
1775
1776         $targetField->setAttribute('class', $targetField->getAttribute('class') . ' crm-chain-select-target');
1777
1778         $css = (string) $controlField->getAttribute('class');
1779         $controlField->updateAttributes(array(
1780           'class' => ($css ? "$css " : 'crm-select2 ') . 'crm-chain-select-control',
1781           'data-target' => $target,
1782         ));
1783         $controlValue = $controlField->getValue();
1784         if ($controlValue) {
1785           $options = CRM_Core_BAO_Location::getChainSelectValues($controlValue, $controlType, TRUE);
1786           if (!$options) {
1787             $targetField->setAttribute('placeholder', $targetField->getAttribute('data-none-prompt'));
1788           }
1789         } else {
1790           $targetField->setAttribute('placeholder', $targetField->getAttribute('data-empty-prompt'));
1791           $targetField->setAttribute('disabled', 'disabled');
1792         }
1793       }
1794       // Control field not present - fall back to loading default options
1795       else {
1796         $options = CRM_Core_PseudoConstant::$targetType();
1797       }
1798       if (!$targetField->getAttribute('multiple')) {
1799         $options = array('' => $targetField->getAttribute('placeholder')) + $options;
1800         $targetField->removeAttribute('placeholder');
1801       }
1802       $targetField->_options = array();
1803       $targetField->loadArray($options);
1804     }
1805   }
1806
1807   /**
1808    * Validate country / state / county match and suppress unwanted "required" errors
1809    */
1810   private function validateChainSelectFields() {
1811     foreach ($this->_chainSelectFields as $control => $target) {
1812       if ($this->elementExists($control)) {
1813         $controlValue = (array)$this->getElementValue($control);
1814         $targetField = $this->getElement($target);
1815         $controlType = $targetField->getAttribute('data-callback') == 'civicrm/ajax/jqCounty' ? 'stateProvince' : 'country';
1816         $targetValue = array_filter((array)$targetField->getValue());
1817         if ($targetValue || $this->getElementError($target)) {
1818           $options = CRM_Core_BAO_Location::getChainSelectValues($controlValue, $controlType, TRUE);
1819           if ($targetValue) {
1820             if (!array_intersect($targetValue, array_keys($options))) {
1821               $this->setElementError($target, $controlType == 'country' ? ts('State/Province does not match the selected Country') : ts('County does not match the selected State/Province'));
1822             }
1823           } // Suppress "required" error for field if it has no options
1824           elseif (!$options) {
1825             $this->setElementError($target, NULL);
1826           }
1827         }
1828       }
1829     }
1830   }
1831 }
1832