CRM/Core/Task.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   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  * @package CRM
  30  * @copyright CiviCRM LLC (c) 2004-2019
  31  */
  32
  33 /**
  34  * Class to represent the actions that can be performed on a group of contacts used by the search forms.
  35  */
  36 abstract class CRM_Core_Task {
  37
  38   /**
  39    * These constants are only used as enumerators for each of the batch tasks.
  40    */
  41   const
  42     // General (Implemented by more than one entity)
  43     GROUP_REMOVE = 1,
  44     GROUP_ADD = 2,
  45     PDF_LETTER = 3,
  46     TASK_DELETE = 4,
  47     TASK_PRINT = 5,
  48     BATCH_UPDATE = 6,
  49     TASK_SMS = 7,
  50     TASK_EXPORT = 8,
  51     TASK_EMAIL = 9,
  52     TAG_ADD = 10,
  53     TAG_REMOVE = 11,
  54     // Contact tasks
  55     SAVE_SEARCH = 12,
  56     SAVE_SEARCH_UPDATE = 13,
  57     CREATE_MAILING = 14,
  58     DELETE_PERMANENTLY = 15,
  59     LABEL_CONTACTS = 16;
  60
  61   /**
  62    * The task array
  63    *
  64    * @var array
  65    */
  66   public static $_tasks = NULL;
  67
  68   /**
  69    * @var string
  70    *   This must be defined in each child class.  It is passed to the searchTasks hook.
  71    *   Example: $objectType = 'event';
  72    */
  73   public static $objectType = NULL;
  74
  75   /**
  76    * Generates a list of batch tasks available for the current entities.
  77    * Each child class should populate $_tasks array and then call this parent function for shared functionality.
  78    *    * @return array The set of tasks for a group of contacts
  79    *            [ 'title' => The Task title,
  80    *              'class' => The Task Form class name,
  81    *              'result => Boolean.  FIXME: Not sure what this is for
  82    *            ]
  83    */
  84   public static function tasks() {
  85     CRM_Utils_Hook::searchTasks(static::$objectType, self::$_tasks);
  86     asort(self::$_tasks);
  87
  88     return self::$_tasks;
  89   }
  90
  91   /**
  92    * These tasks are the core set of tasks that the user can perform
  93    * on a contact / group of contacts
  94    *
  95    * @return array
  96    *   the set of tasks for a group of contacts
  97    */
  98   public static function taskTitles() {
  99     static::tasks();
 100
 101     $titles = [];
 102     foreach (self::$_tasks as $id => $value) {
 103       $titles[$id] = $value['title'];
 104     }
 105
 106     if (!CRM_Utils_Mail::validOutBoundMail()) {
 107       unset($titles[self::TASK_EMAIL]);
 108       unset($titles[self::CREATE_MAILING]);
 109     }
 110
 111     // Users who do not have 'access deleted contacts' should NOT have the 'Delete Permanently' option in search result tasks
 112     if (!CRM_Core_Permission::check('access deleted contacts') ||
 113       !CRM_Core_Permission::check('delete contacts')
 114     ) {
 115       unset($titles[self::DELETE_PERMANENTLY]);
 116     }
 117     return $titles;
 118   }
 119
 120   /**
 121    * Show tasks selectively based on the permission level
 122    * of the user
 123    * This function should be overridden by the child class which would normally call parent::corePermissionedTaskTitles
 124    *
 125    * @param int $permission
 126    * @param array $params
 127    *             "ssID: Saved Search ID": If !empty we are in saved search context
 128    *
 129    * @return array
 130    *   set of tasks that are valid for the user
 131    */
 132   public static function permissionedTaskTitles($permission, $params) {
 133     return self::corePermissionedTaskTitles(self::tasks(), $permission, $params);
 134   }
 135
 136   /**
 137    * Show tasks selectively based on the permission level
 138    * of the user
 139    * This function should be called by permissionedTaskTitles in children
 140    *
 141    * @param array $tasks The array of tasks generated by permissionedTaskTitles
 142    * @param int $permission
 143    * @param array $params
 144    *             "ssID: Saved Search ID": If !empty we are in saved search context
 145    *
 146    * @return array
 147    *   set of tasks that are valid for the user
 148    */
 149   public static function corePermissionedTaskTitles($tasks, $permission, $params) {
 150     // Only offer the "Update Smart Group" task if a smart group/saved search is already in play and we have edit permissions
 151     if (!empty($params['ssID']) && ($permission == CRM_Core_Permission::EDIT)) {
 152       $tasks[self::SAVE_SEARCH_UPDATE] = self::$_tasks[self::SAVE_SEARCH_UPDATE]['title'];
 153     }
 154     else {
 155       unset($tasks[self::SAVE_SEARCH_UPDATE]);
 156     }
 157
 158     asort($tasks);
 159     return $tasks;
 160   }
 161
 162   /**
 163    * These tasks are the core set of tasks that the user can perform
 164    * on participants
 165    *
 166    * @param int $value
 167    *
 168    * @return array
 169    *   the set of tasks for a group of participants
 170    */
 171   public static function getTask($value) {
 172     static::tasks();
 173
 174     if (!CRM_Utils_Array::value($value, self::$_tasks)) {
 175       // Children can specify a default task (eg. print), pick another if it is not valid.
 176       $value = key(self::$_tasks);
 177     }
 178     return [
 179       CRM_Utils_Array::value('class', self::$_tasks[$value]),
 180       CRM_Utils_Array::value('result', self::$_tasks[$value]),
 181     ];
 182   }
 183
 184   /**
 185    * Function to return the task information on basis of provided task's form name
 186    *
 187    * @param string $className
 188    *
 189    * @return array [ 0 => Task ID, 1 => Task Title ]
 190    */
 191   public static function getTaskAndTitleByClass($className) {
 192     static::tasks();
 193
 194     foreach (self::$_tasks as $task => $value) {
 195       if ((!empty($value['url']) || $task == self::TASK_EXPORT)
 196           && ((is_array($value['class']) && in_array($className, $value['class']))
 197           || ($value['class'] == $className))) {
 198         return [$task, CRM_Utils_Array::value('title', $value)];
 199       }
 200     }
 201     return [];
 202   }
 203
 204 }