api/v3/DashboardContact.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM dashboard contacts.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Creates/Updates a new Dashboard Contact Entry.
  20  *
  21  * @param array $params
  22  *
  23  * @return array
  24  */
  25 function civicrm_api3_dashboard_contact_create($params) {
  26   $errors = _civicrm_api3_dashboard_contact_check_params($params);
  27   if ($errors !== NULL) {
  28     return $errors;
  29   }
  30   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'DashboardContact');
  31 }
  32
  33 /**
  34  * Gets a CiviCRM Dashlets of Contacts according to parameters.
  35  *
  36  * @param array $params
  37  *   Array per getfields metadata.
  38  *
  39  * @return array
  40  */
  41 function civicrm_api3_dashboard_contact_get($params) {
  42   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  43 }
  44
  45 /**
  46  * Adjust Metadata for Create action.
  47  *
  48  * The metadata is used for setting defaults, documentation & validation.
  49  *
  50  * @param array $fields
  51  *   Array of fields determined by getfields.
  52  */
  53 function _civicrm_api3_dashboard_contact_create_spec(&$fields) {
  54   $fields['dashboard_id']['api.required'] = TRUE;
  55 }
  56
  57 /**
  58  * Check permissions on contact dashboard retrieval.
  59  *
  60  * @param array $params
  61  *   Array per getfields metadata.
  62  *
  63  * @return array|null
  64  */
  65 function _civicrm_api3_dashboard_contact_check_params(&$params) {
  66   if (!empty($params['dashboard_id'])) {
  67     $allDashlets = CRM_Core_BAO_Dashboard::getDashlets(TRUE, $params['check_permissions'] ?? FALSE);
  68     if (!isset($allDashlets[$params['dashboard_id']])) {
  69       return civicrm_api3_create_error('Invalid or inaccessible dashboard ID');
  70     }
  71   }
  72   return NULL;
  73 }
  74
  75 /**
  76  * Delete an existing dashboard-contact.
  77  *
  78  * @param array $params
  79  *
  80  * @return array
  81  * @throws \API_Exception
  82  */
  83 function civicrm_api3_dashboard_contact_delete($params) {
  84   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  85 }