Commit 19aaebcb authored by Dries's avatar Dries
Browse files

- Patch #721010 by jhodgdon: actions topic group needs more functions included...

- Patch #721010 by jhodgdon: actions topic group needs more functions included and better doc header.
parent abf19a33
......@@ -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.
......
......@@ -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);
......
......@@ -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) {
......
......@@ -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(
......
......@@ -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();
......
......@@ -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)) {
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment