crm.fsf.org/20131203/files/sites/all/modules-old/views_bulk_operations/plugins/operation_types/base.class.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Defines the base class for operations.
   6  */
   7
   8 abstract class ViewsBulkOperationsBaseOperation {
   9
  10   /**
  11    * The id of the operation.
  12    *
  13    * Composed of the operation_type plugin name and the operation key,
  14    * divided by '::'. For example: action::node_publish_action.
  15    */
  16   public $operationId;
  17
  18   /**
  19    * The entity type that the operation is operating on.
  20    *
  21    * Not the same as $operationInfo['type'] since that value can be just
  22    * "entity", which means "available to every entity type".
  23    */
  24   public $entityType;
  25
  26   /**
  27    * Contains information about the current operation, as generated
  28    * by the "list callback" function in the plugin file.
  29    *
  30    * @var array
  31    */
  32   protected $operationInfo;
  33
  34   /**
  35    * Contains the options set by the admin for the current operation.
  36    *
  37    * @var array
  38    */
  39   protected $adminOptions;
  40
  41   /**
  42    * Constructs an operation object.
  43    *
  44    * @param $operationId
  45    *   The id of the operation.
  46    * @param $entityType
  47    *   The entity type that the operation is operating on.
  48    * @param $operationInfo
  49    *   An array of information about the operation.
  50    * @param $adminOptions
  51    *   An array of options set by the admin.
  52    */
  53   public function __construct($operationId, $entityType, array $operationInfo, array $adminOptions) {
  54     $this->operationId = $operationId;
  55     $this->entityType = $entityType;
  56     $this->operationInfo = $operationInfo;
  57     $this->adminOptions = $adminOptions;
  58   }
  59
  60   /**
  61    * Returns the value of an admin option.
  62    */
  63   public function getAdminOption($key, $default = NULL) {
  64     return isset($this->adminOptions[$key]) ? $this->adminOptions[$key] : $default;
  65   }
  66
  67   /**
  68    * Returns the access bitmask for the operation, used for entity access checks.
  69    */
  70   public function getAccessMask() {
  71     // Assume edit by default.
  72     return VBO_ACCESS_OP_UPDATE;
  73   }
  74
  75   /**
  76    * Returns the id of the operation.
  77    */
  78   public function id() {
  79     return $this->operationId;
  80   }
  81
  82   /**
  83    * Returns the name of the operation_type plugin that provides the operation.
  84    */
  85   public function type() {
  86     return $this->operationInfo['operation_type'];
  87   }
  88
  89   /**
  90    * Returns the human-readable name of the operation, meant to be shown
  91    * to the user.
  92    */
  93   public function label() {
  94     $admin_label = $this->getAdminOption('label');
  95     if (!empty($admin_label)) {
  96       $label = t($admin_label);
  97     }
  98     else {
  99       // If the admin didn't specify any label, fallback to the default one.
 100       $label = $this->operationInfo['label'];
 101     }
 102     return $label;
 103   }
 104
 105   /**
 106    * Returns the human-readable name of the operation, meant to be shown
 107    * to the admin.
 108    */
 109   public function adminLabel() {
 110     return $this->operationInfo['label'];
 111   }
 112
 113   /**
 114    * Returns whether the operation is configurable. Used to determine
 115    * whether the operation's form methods should be invoked.
 116    */
 117   public function configurable() {
 118     return !empty($this->operationInfo['configurable']);
 119   }
 120
 121   /**
 122    * Returns whether the provided account has access to execute the operation.
 123    *
 124    * @param $account
 125    */
 126   public function access($account) {
 127     return TRUE;
 128   }
 129
 130   /**
 131    * Returns the configuration form for the operation.
 132    * Only called if the operation is declared as configurable.
 133    *
 134    * @param $form
 135    *   The views form.
 136    * @param $form_state
 137    *   An array containing the current state of the form.
 138    * @param $context
 139    *   An array of related data provided by the caller.
 140    */
 141   abstract function form($form, &$form_state, array $context);
 142
 143   /**
 144    * Validates the configuration form.
 145    * Only called if the operation is declared as configurable.
 146    *
 147    * @param $form
 148    *   The views form.
 149    * @param $form_state
 150    *   An array containing the current state of the form.
 151    */
 152   abstract function formValidate($form, &$form_state);
 153
 154   /**
 155    * Handles the submitted configuration form.
 156    * This is where the operation can transform and store the submitted data.
 157    * Only called if the operation is declared as configurable.
 158    *
 159    * @param $form
 160    *   The views form.
 161    * @param $form_state
 162    *   An array containing the current state of the form.
 163    */
 164   abstract function formSubmit($form, &$form_state);
 165
 166   /**
 167    * Returns the admin options form for the operation.
 168    *
 169    * The admin options form is embedded into the VBO field settings and used
 170    * to configure operation behavior. The options can later be fetched
 171    * through the getAdminOption() method.
 172    *
 173    * @param $dom_id
 174    *   The dom path to the level where the admin options form is embedded.
 175    *   Needed for #dependency.
 176    * @param $field_handler
 177    *   The Views field handler object for the VBO field.
 178    */
 179   public function adminOptionsForm($dom_id, $field_handler) {
 180     $label = $this->getAdminOption('label', '');
 181
 182     $form = array();
 183     $form['override_label'] = array(
 184       '#type' => 'checkbox',
 185       '#title' => t('Override label'),
 186       '#default_value' => $label !== '',
 187       '#dependency' => array(
 188         $dom_id . '-selected' => array(1),
 189       ),
 190     );
 191     $form['label'] = array(
 192       '#type' => 'textfield',
 193       '#title' => t('Provide label'),
 194       '#title_display' => 'invisible',
 195       '#default_value' => $label,
 196       '#dependency' => array(
 197         $dom_id . '-selected' => array(1),
 198         $dom_id . '-override-label' => array(1),
 199       ),
 200       '#dependency_count' => 2,
 201     );
 202
 203     return $form;
 204   }
 205
 206   /**
 207    * Validates the admin options form.
 208    *
 209    * @param $form
 210    *   The admin options form.
 211    * @param $form_state
 212    *   An array containing the current state of the form. Note that this array
 213    *   is constructed by the VBO views field handler, so it's not a real form
 214    *   state, it contains only the 'values' key.
 215    * @param $error_element_base
 216    *   The base to prepend to field names when using form_set_error().
 217    *   Needed because the admin options form is embedded into a bigger form.
 218    */
 219   public function adminOptionsFormValidate($form, &$form_state, $error_element_base) {
 220     // No need to do anything, but make the function have a body anyway
 221     // so that it's callable by overriding methods.
 222   }
 223
 224   /**
 225    * Handles the submitted admin options form.
 226    * Note that there is no need to handle saving the options, that is done
 227    * by the VBO views field handler, which also injects the options into the
 228    * operation object upon instantiation.
 229    *
 230    * @param $form
 231    *   The admin options form.
 232    * @param $form_state
 233    *   An array containing the current state of the form. Note that this array
 234    *   is constructed by the VBO views field handler, so it's not a real form
 235    *   state, it contains only the 'values' key.
 236    */
 237   public function adminOptionsFormSubmit($form, &$form_state) {
 238     // If the "Override label" checkbox was deselected, clear the entered value.
 239     if (empty($form_state['values']['override_label'])) {
 240       $form_state['values']['label'] = '';
 241     }
 242   }
 243
 244   /**
 245    * Returns whether the selected entities should be aggregated
 246    * (loaded in bulk and passed in together).
 247    * To be avoided if possible, since aggregation makes it impossible to use
 248    * Batch API or the Drupal Queue for execution.
 249    */
 250   public function aggregate() {
 251     return !empty($this->operationInfo['aggregate']);
 252   }
 253
 254   /**
 255    * Returns whether the operation needs the full selected views rows to be
 256    * passed to execute() as a part of $context.
 257    */
 258   public function needsRows() {
 259     return FALSE;
 260   }
 261
 262   /**
 263    * Executes the selected operation on the provided data.
 264    *
 265    * @param $data
 266    *   The data to to operate on. An entity or an array of entities.
 267    * @param $context
 268    *   An array of related data (selected views rows, etc).
 269    */
 270   abstract function execute($data, array $context);
 271 }