api/v2/UFGroup.php

   1 <?php
   2 // $Id: UFGroup.php 45502 2013-02-08 13:32:55Z kurund $
   3
   4
   5 /*
   6  +--------------------------------------------------------------------+
   7  | CiviCRM version 4.3                                                |
   8  +--------------------------------------------------------------------+
   9  | Copyright CiviCRM LLC (c) 2004-2013                                |
  10  +--------------------------------------------------------------------+
  11  | This file is a part of CiviCRM.                                    |
  12  |                                                                    |
  13  | CiviCRM is free software; you can copy, modify, and distribute it  |
  14  | under the terms of the GNU Affero General Public License           |
  15  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  16  |                                                                    |
  17  | CiviCRM is distributed in the hope that it will be useful, but     |
  18  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  19  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  20  | See the GNU Affero General Public License for more details.        |
  21  |                                                                    |
  22  | You should have received a copy of the GNU Affero General Public   |
  23  | License and the CiviCRM Licensing Exception along                  |
  24  | with this program; if not, contact CiviCRM LLC                     |
  25  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  26  | GNU Affero General Public License or the licensing of CiviCRM,     |
  27  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  28  +--------------------------------------------------------------------+
  29 */
  30
  31 /**
  32  * File for the CiviCRM APIv2 user framework group functions
  33  *
  34  * @package CiviCRM_APIv2
  35  * @subpackage API_UF
  36  *
  37  * @copyright CiviCRM LLC (c) 2004-2013
  38  * @version $Id: UFGroup.php 45502 2013-02-08 13:32:55Z kurund $
  39  *
  40  */
  41
  42 /**
  43  * Files required for this package
  44  */
  45 require_once 'api/v2/utils.php';
  46 require_once 'CRM/Core/BAO/UFGroup.php';
  47
  48 /**
  49  * Most API functions take in associative arrays ( name => value pairs
  50  * as parameters. Some of the most commonly used parameters are
  51  * described below
  52  *
  53  * @param array $params           an associative array used in construction
  54  *                                / retrieval of the object
  55  * @param array $returnProperties the limited set of object properties that
  56  *                                need to be returned to the caller
  57  *
  58  */
  59
  60 /**
  61  * Get all the user framework groups
  62  *
  63  * @access public
  64  *
  65  * @return array - array reference of all groups.
  66  * @static
  67  */
  68 function &civicrm_uf_profile_groups_get() {
  69   return CRM_Core_PseudoConstant::ufGroup();
  70 }
  71
  72 /**
  73  * Get the form title.
  74  *
  75  * @param int $id id of uf_form
  76  *
  77  * @return string title
  78  *
  79  * @access public
  80  * @static
  81  *
  82  */
  83 function civicrm_uf_profile_title_get($id) {
  84   if ((int) $id > 0) {
  85     return CRM_Core_BAO_UFGroup::getTitle($id);
  86   }
  87   else {
  88     return civicrm_create_error('Param needs to be a positive integer.');
  89   }
  90 }
  91
  92 /**
  93  * get all the fields that belong to the group with the named title
  94  *
  95  * @param int $id       the id of the UF group
  96  * @param int $register are we interested in registration fields
  97  * @param int $action   what action are we doing
  98  * @param string $visibility visibility of fields we are interested in
  99  *
 100  * @return array the fields that belong to this title
 101  * @static
 102  * @access public
 103  */
 104 function civicrm_uf_profile_fields_get($id, $register = FALSE, $action = NULL, $visibility = NULL) {
 105   if ((int) $id > 0) {
 106     return CRM_Core_BAO_UFGroup::getFields($id, $register, $action, NULL, $visibility, FALSE, NULL, TRUE);
 107   }
 108   else {
 109     return civicrm_create_error('Param needs to be a positive integer.');
 110   }
 111 }
 112
 113 /**
 114  * get the html for the form that represents this particular group
 115  *
 116  * @param int     $userID   the user id that we are actually editing
 117  * @param string  $title    the title of the group we are interested in
 118  * @param int     $action   the action of the form
 119  * @param boolean $register is this the registration form
 120  * @param boolean $reset    should we reset the form?
 121  *
 122  * @return string       the html for the form
 123  * @static
 124  * @access public
 125  */
 126 function civicrm_uf_profile_html_get($userID, $title, $action = NULL, $register = FALSE, $reset = FALSE) {
 127   if ((int) $userID > 0 and is_string($title)) {
 128     return CRM_Core_BAO_UFGroup::getEditHTML($userID, $title, $action, $register, $reset);
 129   }
 130   else {
 131     return civicrm_create_error('Params need to be a positive integer and a string.');
 132   }
 133 }
 134
 135 /**
 136  * get the html for the form that represents this particular group
 137  *
 138  * @param int     $userID    the user id that we are actually editing
 139  * @param int     $profileID the id of the group we are interested in
 140  * @param int     $action    the action of the form
 141  * @param boolean $register  is this the registration form
 142  * @param boolean $reset     should we reset the form?
 143  *
 144  * @return string            the html for the form
 145  * @static
 146  * @access public
 147  */
 148 function civicrm_uf_profile_html_by_id_get($userID, $profileID, $action = NULL, $register = FALSE, $reset = FALSE) {
 149   if ((int) $userID > 0 and (int) $profileID > 0) {
 150     return CRM_Core_BAO_UFGroup::getEditHTML($userID, NULL, $action, $register, $reset, $profileID);
 151   }
 152   else {
 153     return civicrm_create_error('Params need to be positive integers.');
 154   }
 155 }
 156
 157 /**
 158  * get the html for the form for profile creation
 159  *
 160  * @param int     $gid      group id
 161  * @param boolean $reset    should we reset the form?
 162  *
 163  * @return string       the html for the form
 164  * @static
 165  * @access public
 166  */
 167 function civicrm_uf_create_html_get($gid, $reset = FALSE) {
 168   if ((int) $gid < 1) {
 169     return civicrm_create_error('Param needs to be a positive integer.');
 170   }
 171
 172   require_once 'CRM/Core/Controller/Simple.php';
 173   $session = CRM_Core_Session::singleton();
 174   $controller = new CRM_Core_Controller_Simple('CRM_Profile_Form_Edit', '', CRM_Core_Action::ADD);
 175   if ($reset) {
 176     unset($_POST['_qf_default']);
 177     unset($_REQUEST['_qf_default']);
 178   }
 179   $controller->set('gid', $gid);
 180   $controller->set('skipPermission', 1);
 181   $controller->process();
 182   $controller->setEmbedded(TRUE);
 183   $controller->run();
 184
 185   $template = CRM_Core_Smarty::singleton();
 186   return trim($template->fetch('CRM/Profile/Form/Dynamic.tpl'));
 187 }
 188
 189 /**
 190  * get the contact_id given a uf_id
 191  *
 192  * @param int $ufID
 193  *
 194  * @return int contact_id
 195  * @access public
 196  * @static
 197  */
 198 function civicrm_uf_match_id_get($ufID) {
 199   if ((int) $ufID > 0) {
 200     require_once 'CRM/Core/BAO/UFMatch.php';
 201     return CRM_Core_BAO_UFMatch::getContactId($ufID);
 202   }
 203   else {
 204     return civicrm_create_error('Param needs to be a positive integer.');
 205   }
 206 }
 207
 208 /**
 209  * get the uf_id given a contact_id
 210  *
 211  * @param int $contactID
 212  *
 213  * @return int ufID
 214  * @access public
 215  * @static
 216  */
 217 function civicrm_uf_id_get($contactID) {
 218   if ((int) $contactID > 0) {
 219     require_once 'CRM/Core/BAO/UFMatch.php';
 220     return CRM_Core_BAO_UFMatch::getUFId($contactID);
 221   }
 222   else {
 223     return civicrm_create_error('Param needs to be a positive integer.');
 224   }
 225 }
 226
 227 /*******************************************************************/
 228
 229 /**
 230  * Use this API to create a new group. See the CRM Data Model for uf_group property definitions
 231  *
 232  * @param $params  array   Associative array of property name/value pairs to insert in group.
 233  *
 234  * @return   Newly create $ufGroupArray array
 235  *
 236  * @access public
 237  */
 238 function civicrm_uf_group_create($params) {
 239   if (!is_array($params) or empty($params) or !isset($params['title'])) {
 240     return civicrm_create_error('Params must be an array and have a title field.');
 241   }
 242
 243   _civicrm_initialize();
 244
 245   $ids = array();
 246   require_once 'CRM/Core/BAO/UFGroup.php';
 247
 248   $ufGroup = CRM_Core_BAO_UFGroup::add($params, $ids);
 249   _civicrm_object_to_array($ufGroup, $ufGroupArray);
 250
 251   return $ufGroupArray;
 252 }
 253
 254 /**
 255  * Use this API to update  group. See the CRM Data Model for uf_group property definitions
 256  *
 257  * @param $params  array   Associative array of property name/value pairs to insert in group.
 258  *
 259  * @param $groupId int  A valid UF Group ID that to be updated.
 260  *
 261  * @return  updated  $ufGroupArray array
 262  *
 263  * @access public
 264  */
 265 function civicrm_uf_group_update($params, $groupId) {
 266   if (!is_array($params) or empty($params) or (int) $groupId < 1) {
 267     return civicrm_create_error('Params must be a non-empty array and a positive integer.');
 268   }
 269
 270   _civicrm_initialize();
 271
 272   $ids = array();
 273   $ids['ufgroup'] = $groupId;
 274
 275   require_once 'CRM/Core/BAO/UFGroup.php';
 276
 277   $ufGroup = CRM_Core_BAO_UFGroup::add($params, $ids);
 278   _civicrm_object_to_array($ufGroup, $ufGroupArray);
 279
 280   return $ufGroupArray;
 281 }
 282
 283 /**
 284  * Defines 'uf field' within a group.
 285  *
 286  * @param $groupId int Valid uf_group id
 287  *
 288  * @param $params  array  Associative array of property name/value pairs to create new uf field.
 289  *
 290  * @return Newly created $ufFieldArray array
 291  *
 292  * @access public
 293  *
 294  */
 295 function civicrm_uf_field_create($groupId, $params) {
 296   if (!is_array($params) or !isset($params['field_name']) or (int) $groupId < 1) {
 297     return civicrm_create_error('Params must be a field_name-carrying array and a positive integer.');
 298   }
 299
 300   _civicrm_initialize();
 301
 302   $field_type       = CRM_Utils_Array::value('field_type', $params);
 303   $field_name       = CRM_Utils_Array::value('field_name', $params);
 304   $location_type_id = CRM_Utils_Array::value('location_type_id', $params);
 305   $phone_type       = CRM_Utils_Array::value('phone_type', $params);
 306
 307   $params['field_name'] = array($field_type, $field_name, $location_type_id, $phone_type);
 308
 309   if (!(CRM_Utils_Array::value('group_id', $params))) {
 310     $params['group_id'] = $groupId;
 311   }
 312
 313   $ids = array();
 314   $ids['uf_group'] = $groupId;
 315
 316   require_once 'CRM/Core/BAO/UFField.php';
 317   if (CRM_Core_BAO_UFField::duplicateField($params, $ids)) {
 318     return civicrm_create_error("The field was not added. It already exists in this profile.");
 319   }
 320
 321   $params['weight'] = CRM_Core_BAO_UFField::autoWeight($params);
 322   $ufField = CRM_Core_BAO_UFField::add($params, $ids);
 323   _civicrm_object_to_array($ufField, $ufFieldArray);
 324
 325   return $ufFieldArray;
 326 }
 327
 328 /**
 329  * Use this API to update uf field . See the CRM Data Model for uf_field property definitions
 330  *
 331  * @param $params  array   Associative array of property name/value pairs to update in field.
 332  *
 333  * @param $fieldId int  A valid uf field id that to be updated.
 334  *
 335  * @return  updated  $ufFieldArray array
 336  *
 337  * @access public
 338  */
 339 function civicrm_uf_field_update($params, $fieldId) {
 340
 341   _civicrm_initialize();
 342
 343   if (!isset($fieldId)) {
 344     return civicrm_create_error("parameter fieldId is not set");
 345   }
 346
 347   if (!is_array($params)) {
 348     return civicrm_create_error("params is not an array ");
 349   }
 350
 351   $field_type       = CRM_Utils_Array::value('field_type', $params);
 352   $field_name       = CRM_Utils_Array::value('field_name', $params);
 353   $location_type_id = CRM_Utils_Array::value('location_type_id', $params);
 354   $phone_type       = CRM_Utils_Array::value('phone_type', $params);
 355
 356   $params['field_name'] = array($field_type, $field_name, $location_type_id, $phone_type);
 357
 358   require_once 'CRM/Core/BAO/UFField.php';
 359   $UFField = new CRM_core_BAO_UFField();
 360   $UFField->id = $fieldId;
 361
 362   if (!(CRM_Utils_Array::value('group_id', $params)) && $UFField->find(TRUE)) {
 363     $params['group_id'] = $UFField->uf_group_id;
 364   }
 365
 366   $ids = array();
 367
 368   if ($UFField->find(TRUE)) {
 369     $ids['uf_group'] = $UFField->uf_group_id;
 370   }
 371   else {
 372     return civicrm_create_error("there is no field for this fieldId");
 373   }
 374   $ids['uf_field'] = $fieldId;
 375
 376   if (CRM_Core_BAO_UFField::duplicateField($params, $ids)) {
 377     return civicrm_create_error("The field was not added. It already exists in this profile.");
 378   }
 379
 380   $params['weight'] = CRM_Core_BAO_UFField::autoWeight($params);
 381   $ufField = CRM_Core_BAO_UFField::add($params, $ids);
 382   _civicrm_object_to_array($ufField, $ufFieldArray);
 383
 384   return $ufFieldArray;
 385 }
 386
 387 /**
 388  * Delete uf group
 389  *
 390  * @param $groupId int  Valid uf_group id that to be deleted
 391  *
 392  * @return true on successful delete or return error
 393  *
 394  * @access public
 395  *
 396  */
 397 function civicrm_uf_group_delete($groupId) {
 398   _civicrm_initialize();
 399
 400   if (!isset($groupId)) {
 401     return civicrm_create_error("provide a valid groupId.");
 402   }
 403
 404   require_once 'CRM/Core/BAO/UFGroup.php';
 405   return CRM_Core_BAO_UFGroup::del($groupId);
 406 }
 407
 408 /**
 409  * Delete uf field
 410  *
 411  * @param $fieldId int  Valid uf_field id that to be deleted
 412  *
 413  * @return true on successful delete or return error
 414  *
 415  * @access public
 416  *
 417  */
 418 function civicrm_uf_field_delete($fieldId) {
 419   _civicrm_initialize();
 420
 421   if (!isset($fieldId)) {
 422     return civicrm_create_error("provide a valid fieldId.");
 423   }
 424
 425   require_once 'CRM/Core/BAO/UFField.php';
 426   return CRM_Core_BAO_UFField::del($fieldId);
 427 }
 428
 429 /**
 430  * check the data validity
 431  *
 432  * @param int    $userID    the user id
 433  * @param string $title     the title of the group we are interested in
 434  * @param  boolean $register is this the registrtion form
 435  * @param int    $action  the action of the form
 436  *
 437  * @return error   if data not valid
 438  *
 439  * @access public
 440  */
 441 function civicrm_profile_html_validate($userID, $title, $action = NULL, $register = FALSE) {
 442   return CRM_Core_BAO_UFGroup::isValid($userID, $title, $register, $action);
 443 }
 444
 445 /**
 446  * used to edit uf field
 447  *
 448  * @param array as key value pair
 449
 450  *
 451  * @return error   if updation fails else array of updated data
 452  *
 453  * @access public
 454  */
 455 function civicrm_uf_group_weight($params) {
 456   unset($params['fnName']);
 457   require_once 'CRM/Core/DAO/UFField.php';
 458   foreach ($params as $key => $value) {
 459     $value['is_active'] = 1;
 460     $result[] = civicrm_uf_field_update($value, $key);
 461   }
 462   return $result;
 463 }
 464