diff options
Diffstat (limited to 'includes/actions.inc')
| -rw-r--r-- | includes/actions.inc | 180 |
1 files changed, 75 insertions, 105 deletions
diff --git a/includes/actions.inc b/includes/actions.inc index 5650bc64f..65089b6ac 100644 --- a/includes/actions.inc +++ b/includes/actions.inc @@ -7,35 +7,31 @@ */ /** - * Perform a given list of actions by executing their callback functions. + * Performs a given list of actions by executing their callback functions. * - * Given the IDs of actions to perform, find out what the callbacks - * for the actions are by querying the database. Then call each callback - * using the function call $function($object, $context, $a1, $a2) - * where $function is the name of a function written in compliance with - * the action specification; that is, foo($object, $context). + * Given the IDs of actions to perform, this function finds out what the + * callback functions for the actions are by querying the database. Then + * it calls each callback using the function call $function($object, $context, + * $a1, $a2), passing the input arguments of this function (see below) to the + * action function. * * @param $action_ids - * The ID of the action to perform. Can be a single action ID or an array - * of IDs. IDs of instances will be numeric; IDs of singletons will be - * function names. + * The IDs of the actions to perform. Can be a single action ID or an array + * of IDs. IDs of configurable actions must be given as numeric action IDs; + * IDs of non-configurable actions may be given as action function names. * @param $object - * Parameter that will be passed along to the callback. Typically the - * object that the action will act on; a node, user or comment object. + * The object that the action will act on: a node, user, or comment object. * @param $context - * Parameter that will be passed along to the callback. $context is a - * keyed array containing extra information about what is currently - * happening at the time of the call. Typically $context['hook'] and - * $context['op'] will tell which hook-op combination resulted in this - * call to actions_do(). + * Associative array containing extra information about what triggered + * the action call, with $context['hook'] giving the name of the hook + * that resulted in this call to actions_do(). * @param $a1 - * Parameter that will be passed along to the callback. + * Passed along to the callback. * @param $a2 - * Parameter that will be passed along to the callback. - * + * Passed along to the callback. * @return - * An associative array containing the result of the function that - * performs the action, keyed on action ID. + * An associative array containing the results of the functions that + * perform the actions, keyed on action ID. */ function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL) { // $stack tracks the number of recursive calls. @@ -109,49 +105,20 @@ function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a } /** - * Discover all action functions by invoking hook_action_info(). - * - * @code - * mymodule_action_info() { - * return array( - * 'mymodule_functiondescription_action' => array( - * 'type' => 'node', - * 'description' => t('Save node'), - * 'configurable' => FALSE, - * 'hooks' => array( - * 'node' => array('delete', 'insert', 'update', 'view'), - * 'comment' => array('delete', 'insert', 'update', 'view'), - * ) - * ) - * ); - * } - * @endcode + * Discovers all available actions by invoking hook_action_info(). * - * The description is used in presenting possible actions to the user for - * configuration. The type is used to present these actions in a logical - * grouping and to denote context. Some types are 'node', 'user', 'comment', - * and 'system'. If an action is configurable it will provide form, - * validation and submission functions. The hooks the action supports - * are declared in the 'hooks' array. + * This function contrasts with actions_get_all_actions(); see the + * documentation of actions_get_all_actions() for an explanation. * * @param $reset * Reset the action info static cache. - * * @return - * An associative array keyed on function name. The value of each key is - * an array containing information about the action, such as type of - * action and description of the action, e.g.: - * @code - * $actions['node_publish_action'] = array( - * 'type' => 'node', - * 'description' => t('Publish post'), - * 'configurable' => FALSE, - * 'hooks' => array( - * 'node' => array('presave', 'insert', 'update', 'view'), - * 'comment' => array('delete', 'insert', 'update', 'view'), - * ), - * ); - * @endcode + * An associative array keyed on action function name, with the same format + * as the return value of hook_action_info(), containing all + * modules' hook_action_info() return values as modified by any + * hook_action_info_alter() implementations. + * + * @see hook_action_info() */ function actions_list($reset = FALSE) { static $actions; @@ -165,19 +132,24 @@ function actions_list($reset = FALSE) { } /** - * Retrieve all action instances from the database. + * Retrieves all action instances from the database. * - * Compare with actions_list() which gathers actions by invoking - * hook_action_info(). The two are synchronized by visiting - * /admin/structure/actions (when actions.module is enabled) which runs - * actions_synchronize(). + * This function differs from the actions_list() function, which gathers + * actions by invoking hook_action_info(). The actions returned by this + * function and the actions returned by actions_list() are partially + * synchronized. Non-configurable actions from hook_action_info() + * implementations are put into the database when actions_synchronize() is + * called, which happens when admin/config/system/actions is visited. Configurable + * actions are not added to the database until they are configured in the + * user interface, in which case a database row is created for each + * configuration of each action. * * @return - * Associative array keyed by action ID. Each value is an associative array - * with keys 'callback', 'description', 'type' and 'configurable'. + * Associative array keyed by numeric action ID. Each value is an associative + * array with keys 'callback', 'label', 'type' and 'configurable'. */ function actions_get_all_actions() { - $actions = db_query("SELECT aid, type, callback, parameters, description FROM {actions}")->fetchAllAssoc('aid', PDO::FETCH_ASSOC); + $actions = db_query("SELECT aid, type, callback, parameters, label FROM {actions}")->fetchAllAssoc('aid', PDO::FETCH_ASSOC); foreach ($actions as &$action) { $action['configurable'] = (bool) $action['parameters']; unset($action['parameters']); @@ -187,28 +159,26 @@ function actions_get_all_actions() { } /** - * Create an associative array keyed by md5 hashes of function names. + * Creates an associative array keyed by md5 hashes of function names or IDs. * * Hashes are used to prevent actual function names from going out into HTML * forms and coming back. * * @param $actions - * An associative array with function names as keys and associative arrays - * with keys 'description', 'type', etc. as values. Generally the output of - * actions_list() or actions_get_all_actions() is given as input to this - * function. - * + * An associative array with function names or action IDs as keys + * and associative arrays with keys 'label', 'type', etc. as values. + * This is usually the output of actions_list() or actions_get_all_actions(). * @return - * An associative array keyed on md5 hash of function names. The value of - * each key is an associative array of function, description, and type for - * the action. + * An associative array whose keys are md5 hashes of the input array keys, and + * whose corresponding values are associative arrays with components + * 'callback', 'label', 'type', and 'configurable' from the input array. */ function actions_actions_map($actions) { $actions_map = array(); foreach ($actions as $callback => $array) { $key = md5($callback); $actions_map[$key]['callback'] = isset($array['callback']) ? $array['callback'] : $callback; - $actions_map[$key]['description'] = $array['description']; + $actions_map[$key]['label'] = $array['label']; $actions_map[$key]['type'] = $array['type']; $actions_map[$key]['configurable'] = $array['configurable']; } @@ -216,17 +186,19 @@ function actions_actions_map($actions) { } /** - * Given an md5 hash of a function name, return the function name. + * Given an md5 hash of an action array key, returns the key (function or ID). * - * Faster than actions_actions_map() when you only need the function name. + * Faster than actions_actions_map() when you only need the function name or ID. * * @param $hash - * MD5 hash of a function name. - * + * MD5 hash of a function name or action ID array key. The array key + * is a key into the return value of actions_list() (array key is the action + * function name) or actions_get_all_actions() (array key is the action ID). * @return - * The corresponding function name or FALSE if none is found. + * The corresponding array key, or FALSE if no match is found. */ function actions_function_lookup($hash) { + // Check for a function name match. $actions_list = actions_list(); foreach ($actions_list as $function => $array) { if (md5($function) == $hash) { @@ -234,26 +206,26 @@ function actions_function_lookup($hash) { } } - // Must be an instance; must check database. + // Must be a configurable action; check database. return db_query("SELECT aid FROM {actions} WHERE MD5(aid) = :hash AND parameters <> ''", array(':hash' => $hash))->fetchField(); } /** - * Synchronize actions that are provided by modules. + * Synchronizes actions that are provided by modules in hook_action_info(). * - * Actions provided by modules are synchronized with actions that are stored in - * the actions table. This is necessary so that actions that do not require - * configuration can receive action IDs. This is not necessarily the best - * approach, but it is the most straightforward. + * Actions provided by modules in hook_action_info() implementations are + * synchronized with actions that are stored in the actions database table. + * This is necessary so that actions that do not require configuration can + * receive action IDs. * * @param $delete_orphans - * Boolean if TRUE, any actions that exist in the database but are no longer + * If TRUE, any actions that exist in the database but are no longer * found in the code (for example, because the module that provides them has * been disabled) will be deleted. */ function actions_synchronize($delete_orphans = FALSE) { $actions_in_code = actions_list(TRUE); - $actions_in_db = db_query("SELECT aid, callback, description FROM {actions} WHERE parameters = ''")->fetchAllAssoc('callback', PDO::FETCH_ASSOC); + $actions_in_db = db_query("SELECT aid, callback, label FROM {actions} WHERE parameters = ''")->fetchAllAssoc('callback', PDO::FETCH_ASSOC); // Go through all the actions provided by modules. foreach ($actions_in_code as $callback => $array) { @@ -272,10 +244,10 @@ function actions_synchronize($delete_orphans = FALSE) { 'type' => $array['type'], 'callback' => $callback, 'parameters' => '', - 'description' => $array['description'], + 'label' => $array['label'], )) ->execute(); - watchdog('actions', "Action '%action' added.", array('%action' => filter_xss_admin($array['description']))); + watchdog('actions', "Action '%action' added.", array('%action' => filter_xss_admin($array['label']))); } } } @@ -285,10 +257,10 @@ function actions_synchronize($delete_orphans = FALSE) { $orphaned = array_keys($actions_in_db); if ($delete_orphans) { - $actions = db_query('SELECT aid, description FROM {actions} WHERE callback IN (:orphaned)', array(':orphaned' => $orphaned))->fetchAll(); + $actions = db_query('SELECT aid, label FROM {actions} WHERE callback IN (:orphaned)', array(':orphaned' => $orphaned))->fetchAll(); foreach ($actions as $action) { actions_delete($action->aid); - watchdog('actions', "Removed orphaned action '%action' from database.", array('%action' => filter_xss_admin($action->description))); + watchdog('actions', "Removed orphaned action '%action' from database.", array('%action' => filter_xss_admin($action->label))); } } else { @@ -301,7 +273,7 @@ function actions_synchronize($delete_orphans = FALSE) { } /** - * Save an action and its associated user-supplied parameter values to the database. + * Saves an action and its user-supplied parameter values to the database. * * @param $function * The name of the function to be called when this action is performed. @@ -311,16 +283,15 @@ function actions_synchronize($delete_orphans = FALSE) { * @param $params * An associative array with parameter names as keys and parameter values as * values. - * @param $desc - * A user-supplied description of this particular action, e.g., 'Send e-mail + * @param $label + * A user-supplied label of this particular action, e.g., 'Send e-mail * to Jim'. * @param $aid * The ID of this action. If omitted, a new action is created. - * * @return * The ID of the action. */ -function actions_save($function, $type, $params, $desc, $aid = NULL) { +function actions_save($function, $type, $params, $label, $aid = NULL) { // aid is the callback for singleton actions so we need to keep a separate // table for numeric aids. if (!$aid) { @@ -333,29 +304,28 @@ function actions_save($function, $type, $params, $desc, $aid = NULL) { 'callback' => $function, 'type' => $type, 'parameters' => serialize($params), - 'description' => $desc, + 'label' => $label, )) ->execute(); - watchdog('actions', 'Action %action saved.', array('%action' => $desc)); + watchdog('actions', 'Action %action saved.', array('%action' => $label)); return $aid; } /** - * Retrieve a single action from the database. + * Retrieves a single action from the database. * * @param $aid * The ID of the action to retrieve. - * * @return * The appropriate action row from the database as an object. */ function actions_load($aid) { - return db_query("SELECT aid, type, callback, parameters, description FROM {actions} WHERE aid = :aid", array(':aid' => $aid))->fetchObject(); + return db_query("SELECT aid, type, callback, parameters, label FROM {actions} WHERE aid = :aid", array(':aid' => $aid))->fetchObject(); } /** - * Delete a single action from the database. + * Deletes a single action from the database. * * @param $aid * The ID of the action to delete. |