diff options
| -rw-r--r-- | includes/actions.inc | 21 | ||||
| -rw-r--r-- | modules/comment/comment.module | 30 | ||||
| -rw-r--r-- | modules/node/node.module | 51 | ||||
| -rw-r--r-- | modules/system/system.api.php | 2 | ||||
| -rw-r--r-- | modules/system/system.module | 50 | ||||
| -rw-r--r-- | modules/user/user.module | 3 |
6 files changed, 117 insertions, 40 deletions
diff --git a/includes/actions.inc b/includes/actions.inc index 6921e2f44..3a73c671b 100644 --- a/includes/actions.inc +++ b/includes/actions.inc @@ -11,16 +11,17 @@ * @{ * Functions that perform an action on a certain system object. * - * All modules should declare their action functions to be in this group and - * each action function should reference its configuration form, validate, and - * submit functions using \@see. Conversely, form, validate, and submit - * functions should reference the action function using \@see. For examples of - * this see comment_unpublish_by_keyword_action(), which has the following in - * its doxygen documentation: + * Action functions are declared by modules by implementing hook_action_info(). + * Modules can cause action functions to run by calling actions_do(), and + * trigger.module provides a user interface that lets administrators define + * events that cause action functions to run. * - * \@ingroup actions - * \@see comment_unpublish_by_keyword_action_form(). - * \@see comment_unpublish_by_keyword_action_submit(). + * Each action function takes two to four arguments: + * - $entity: The object that the action acts on, such as a node, comment, or + * user. + * - $context: Array of additional information about what triggered the action. + * - $a1, $a2: Optional additional information, which can be passed into + * actions_do() and will be passed along to the action function. * * @} End of "defgroup actions". */ @@ -51,6 +52,8 @@ * @return * An associative array containing the results of the functions that * perform the actions, keyed on action ID. + * + * @ingroup actions */ function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL) { // $stack tracks the number of recursive calls. diff --git a/modules/comment/comment.module b/modules/comment/comment.module index 0035b0a99..9758877c6 100644 --- a/modules/comment/comment.module +++ b/modules/comment/comment.module @@ -2360,8 +2360,6 @@ function vancode2int($c = '00') { /** * Implements hook_action_info(). - * - * @ingroup actions */ function comment_action_info() { return array( @@ -2396,12 +2394,13 @@ function comment_action_info() { } /** - * Action to publish a comment. + * Publishes a comment. * * @param $comment * An optional comment object. - * @param $context - * Keyed array. Must contain the id of the comment if $comment is not passed. + * @param array $context + * Array with components: + * - 'cid': Comment ID. Required if $comment is not given. * * @ingroup actions */ @@ -2422,12 +2421,13 @@ function comment_publish_action($comment, $context = array()) { } /** - * Action to unpublish a comment. + * Unpublishes a comment. * * @param $comment * An optional comment object. - * @param $context - * Keyed array. Must contain the id of the comment if $comment is not passed. + * @param array $context + * Array with components: + * - 'cid': Comment ID. Required if $comment is not given. * * @ingroup actions */ @@ -2448,12 +2448,14 @@ function comment_unpublish_action($comment, $context = array()) { } /** - * Action to unpublish a comment if it contains a certain string. + * Unpublishes a comment if it contains certain keywords. * * @param $comment - * A comment object. - * @param $context - * Keyed array. Must contain the id of the comment if $comment is not passed. + * Comment object to modify. + * @param array $context + * Array with components: + * - 'keywords': Keywords to look for. If the comment contains at least one + * of the keywords, it is unpublished. * * @ingroup actions * @see comment_unpublish_by_keyword_action_form() @@ -2498,7 +2500,9 @@ function comment_unpublish_by_keyword_action_submit($form, $form_state) { } /** - * Action to save a comment. + * Saves a comment. + * + * @ingroup actions */ function comment_save_action($comment) { comment_save($comment); diff --git a/modules/node/node.module b/modules/node/node.module index 325fea047..9e6b76045 100644 --- a/modules/node/node.module +++ b/modules/node/node.module @@ -3322,7 +3322,9 @@ function node_action_info() { } /** - * Implements a Drupal action: sets the status of a node to 1 (published). + * Sets the status of a node to 1 (published). + * + * @ingroup actions */ function node_publish_action($node, $context = array()) { $node->status = NODE_PUBLISHED; @@ -3330,7 +3332,9 @@ function node_publish_action($node, $context = array()) { } /** - * Implements a Drupal action: sets the status of a node to 0 (unpublished). + * Sets the status of a node to 0 (unpublished). + * + * @ingroup actions */ function node_unpublish_action($node, $context = array()) { $node->status = NODE_NOT_PUBLISHED; @@ -3338,7 +3342,9 @@ function node_unpublish_action($node, $context = array()) { } /** - * Implements a Drupal action: sets sticky-at-top-of-list property to 1. + * Sets the sticky-at-top-of-list property of a node to 1. + * + * @ingroup actions */ function node_make_sticky_action($node, $context = array()) { $node->sticky = NODE_STICKY; @@ -3346,7 +3352,9 @@ function node_make_sticky_action($node, $context = array()) { } /** - * Implements a Drupal action: sets sticky-at-top-of-list property to 0. + * Sets the sticky-at-top-of-list property of a node to 0. + * + * @ingroup actions */ function node_make_unsticky_action($node, $context = array()) { $node->sticky = NODE_NOT_STICKY; @@ -3354,7 +3362,9 @@ function node_make_unsticky_action($node, $context = array()) { } /** - * Implements a Drupal action: sets the promote property of a node to 1. + * Sets the promote property of a node to 1. + * + * @ingroup actions */ function node_promote_action($node, $context = array()) { $node->promote = NODE_PROMOTED; @@ -3362,7 +3372,9 @@ function node_promote_action($node, $context = array()) { } /** - * Implements a Drupal action: sets the promote property of a node to 0. + * Sets the promote property of a node to 0. + * + * @ingroup actions */ function node_unpromote_action($node, $context = array()) { $node->promote = NODE_NOT_PROMOTED; @@ -3370,7 +3382,9 @@ function node_unpromote_action($node, $context = array()) { } /** - * Implements a Drupal action: saves a node. + * Saves a node. + * + * @ingroup actions */ function node_save_action($node) { node_save($node); @@ -3378,7 +3392,15 @@ function node_save_action($node) { } /** - * Implements a configurable Drupal action: assigns ownership of node to user. + * Assigns ownership of a node to a user. + * + * @param $node + * A node object to modify. + * @param $context + * Array with the following elements: + * - 'owner_uid': User ID to assign to the node. + * + * @ingroup actions */ function node_assign_owner_action($node, $context) { $node->uid = $context['owner_uid']; @@ -3387,7 +3409,7 @@ function node_assign_owner_action($node, $context) { } /** - * Generates settings form for node_assign_owner_action(). + * Generates the settings form for node_assign_owner_action(). */ function node_assign_owner_action_form($context) { $description = t('The username of the user to which you would like to assign ownership.'); @@ -3466,13 +3488,16 @@ function node_unpublish_by_keyword_action_submit($form, $form_state) { } /** - * Implements a configurable Drupal action: unpublish node containing keywords. + * Unpublishes a node containing certain keywords. * * @param $node - * A node object. + * A node object to modify. * @param $context - * An array providing more information about the context of the call to this - * action. + * Array with the following elements: + * - 'keywords': Array of keywords. If any keyword is present in the rendered + * node, the node's status flag is set to unpublished. + * + * @ingroup actions */ function node_unpublish_by_keyword_action($node, $context) { foreach ($context['keywords'] as $keyword) { diff --git a/modules/system/system.api.php b/modules/system/system.api.php index 683c7a82c..4342498cb 100644 --- a/modules/system/system.api.php +++ b/modules/system/system.api.php @@ -2690,6 +2690,8 @@ function hook_file_mimetype_mapping_alter(&$mapping) { * Modules that are processing actions (like Trigger module) should take * special care for the "presave" hook, in which case a dependent "save" * action should NOT be invoked. + * + * @ingroup actions */ function hook_action_info() { return array( diff --git a/modules/system/system.module b/modules/system/system.module index 5536cc757..18ada5af7 100644 --- a/modules/system/system.module +++ b/modules/system/system.module @@ -2859,7 +2859,22 @@ function system_send_email_action_submit($form, $form_state) { } /** - * Implements a configurable Drupal action: sends an email. + * Sends an e-mail message. + * + * @param object $entity + * An optional node object, which will be added as $context['node'] if + * provided. + * @param array $context + * Array with the following elements: + * - 'recipient': E-mail message recipient. This will be passed through + * token_replace(). + * - 'subject': The subject of the message. This will be passed through + * token_replace(). + * - 'message': The message to send. This will be passed through + * token_replace(). + * - Other elements will be used as the data for token replacement. + * + * @ingroup actions */ function system_send_email_action($entity, $context) { if (empty($context['node'])) { @@ -2909,7 +2924,19 @@ function system_message_action_submit($form, $form_state) { } /** - * A configurable Drupal action. Sends a message to the current user's screen. + * Sends a message to the current user's screen. + * + * @param object $entity + * An optional node object, which will be added as $context['node'] if + * provided. + * @param array $context + * Array with the following elements: + * - 'message': The message to send. This will be passed through + * token_replace(). + * - Other elements will be used as the data for token replacement in + * the message. + * + * @ingroup actions */ function system_message_action(&$entity, $context = array()) { if (empty($context['node'])) { @@ -2921,7 +2948,7 @@ function system_message_action(&$entity, $context = array()) { } /** - * Implements a configurable Drupal action: redirect user to a URL. + * Settings form for system_goto_action(). */ function system_goto_action_form($context) { $form['url'] = array( @@ -2940,12 +2967,27 @@ function system_goto_action_submit($form, $form_state) { ); } +/** + * Redirects to a different URL. + * + * @param $entity + * Ignored. + * @param array $context + * Array with the following elements: + * - 'url': URL to redirect to. This will be passed through + * token_replace(). + * - Other elements will be used as the data for token replacement. + * + * @ingroup actions + */ function system_goto_action($entity, $context) { drupal_goto(token_replace($context['url'], $context)); } /** - * Implements a Drupal action: blocks the user's IP address. + * Blocks the current user's IP address. + * + * @ingroup actions */ function system_block_ip_action() { $ip = ip_address(); diff --git a/modules/user/user.module b/modules/user/user.module index f99fe2ea9..0d3fced7f 100644 --- a/modules/user/user.module +++ b/modules/user/user.module @@ -3243,8 +3243,9 @@ function user_action_info() { } /** - * Implement a Drupal action. * Blocks the current user. + * + * @ingroup actions */ function user_block_user_action(&$entity, $context = array()) { if (isset($entity->uid)) { |