<?php
/**
* @file
* Action definition example module.
*//**
* @defgroup action_example Example: Action
* @ingroup examples
* @{
* Creating actions in Drupal 7
*
* Triggers and actions are a matched pair of Drupal features allowing some
* Drupal programming without using PHP. Using the appropriate action in a
* specific event, a site administrator can add new functionality.
*
* Examples are:
* - Send an email after a node is published or edited.
* - Display a message after a user has logged in.
* - Display a message and send an email after a node has been deleted.
*
* A trigger is a special function which can enqueue actions. The trigger module
* provides the interface allowing us to associate certain actions with certain
* triggers.
*
* Actions are the functions designed to be run by triggers.
*
* A trigger should build the appropriate context for the action to be fired.
* Actions are very often grouped by functionality: examples are 'user', 'node',
* 'taxonomy'. When actions are grouped it is because they expect the same
* arguments. This way, you can enqueue as many actions understanding the 'user'
* object as you want.
*
* Not all actions can be used in all triggers because they require different
* contexts. But some actions are generic enough that they do not require
* special objects in their contexts, and so can be used on every available
* trigger. This 'group' type is used by actions to be available for this
* trigger.
*
* What are good candidates to be triggers? Any function can be a trigger, as
* long as it has the code to call the enqueued actions, but to make Drupal
* more extensible, you will find hooks (from Drupal and contributed modules)
* very good candidates. A trigger should build the arguments, ask for enqueued
* actions and run them. You may define a function being a trigger, and run it
* through a button in the front page, or you may prepare a trigger for a hook,
* and everytime that hook is fired, your trigger will be.
*
* What are good candidates to be actions? any function is a possible action,
* the only problem is finding a trigger able to run it.
*
* This module describes how to create actions for Drupal. In this
* example we are providing three actions:
*
* - A generic action that can be used in any trigger, which is the most
* basic example of an action.
*
* - An action which which extends the capabilities of User triggers, even if
* associated with node or comment events.
*
* - An action which extends the capabilities of node triggers, but limited
* to certain events only, and using a customizable option.
*
* @see trigger_example
* @see hook_action_info()
* @see @link http://drupal.org/node/172152 Writing Actions in Drupal 6 @endlink
* @see @link http://drupal.org/node/199254 Triggers and Actions in Drupal 6 @endlink
*//**
* Implements hook_action_info().
*
* We call hook_action_info when we are defining the actions we provide.
* Actions are the actions fired by the associated triggers. In this example,
* we are registering our three new actions, providing the unique name (using
* Drupal's convention modulename_description_action), an easy to understand
* description of what the action does, the 'object' expected by this action
* (default options from core are node, user, comment and system, however other
* trigger modules may declare new object types), which are the triggers allowed
* to use these action, and if some customization is available. Please, note
* that the function name is not required to finish as _action to be declared as
* a Drupal action, and that only information provided by hook_trigger_info()
* will be considered for valid actions creation.
*
* These are the actions being provided in hook_action_info()
*
* - action_example_basic_action: this action is a dummy function which can be
* used by any trigger. The label describes that the action will do nothing,
* but is enough for a basic example. Type is set to system, so users will not
* be confused about the scope of this action (expecting a node, user, or any
* other object). This action is not configurable, and will appear as
* available in the list of action under the menu entry:
* 'admin/config/system/actions.
* - action_example_unblock_user_action: Unblocks a user.
* - action_example_node_sticky_action: This action is a complex action that is
* only available to Node type triggers, and can only be associated with the
* events node presave, node insert and node update. The action does not
* exist by default and it has to be created by user configuration. This makes
* it an "advanced action" in Drupal, so-called because it requires
* configuration or customization.
* In this example action, the action will promote nodes and make them sticky
* during presave, insert, or update, but only for particular users. As an
* advanced action, it first needs to be created in the actions management
* page (admin/config/system/actions). At the bottom of that page a selection
* list shows a list of advanced actions that will includes the option
* 'Promote to frontpage and sticky on top any content created by :'
* Selecting this option and clicking the 'Create' button, a configuration
* form will ask for an author name. When this action is associated to any
* of the possible Node trigger events, it will only be effective if the
* author of the content matches the author configured by the action.
*
* @return
* An associative array of action descriptions. The keys of the array
* are the names of the action functions, and each corresponding value
* is an associative array with the following key-value pairs:
* - 'type': The type of object this action acts upon. Core actions have types
* 'node', 'user', 'comment', and 'system', but additional types can be
* used, as long as the trigger and action agree on them.
* - 'label': The human-readable name of the action, which should be passed
* through the t() function for translation.
* - 'configurable': If FALSE, then the action doesn't require any extra
* configuration. If TRUE, then your module must define a form function with
* the same name as the action function with '_form' appended (e.g., the
* form for 'node_assign_owner_action' is 'node_assign_owner_action_form'.)
* This function takes $context as its only parameter, and is paired with
* the usual _submit function, and possibly an _validate function.
* - 'triggers': An array of the triggers that can trigger this
* action. For example: array('node_insert', 'user_update'). You can also
* declare support for any trigger by returning array('any') for this value.
* - 'behavior': (optional) A machine-readable array of behaviors of this
* action, used to signal additionally required actions that may need to be
* triggered. Currently recognized behaviors by Trigger module:
* - 'changes_property': If an action with this behavior is assigned to a
* trigger other than a "presave" hook, any save actions also assigned to
* this trigger are moved later in the list. If no save action is present,
* one will be added.
* Modules that are processing actions (like Trigger module) should take
* special care in the "presave" hook, in which case a dependent "save"
* action should NOT be invoked.
*
* @see hook_action_info()
*/functionaction_example_action_info() {
returnarray(
'action_example_basic_action' => array(
'label' => t('Action Example: A basic example action that does nothing'),
'type' => 'system',
'configurable' => FALSE,
'triggers' => array('any'),
),
'action_example_unblock_user_action' => array(
'label' => t('Action Example: Unblock a user'),
'type' => 'user',
'configurable' => FALSE,
'triggers' => array('any'),
),
'action_example_node_sticky_action' => array(
'type' => 'node',
'label' => t('Action Example: Promote to frontpage and sticky on top any content created by :'),
'configurable' => TRUE,
'behavior' => array('changes_property'),
'triggers' => array('node_presave', 'node_insert', 'node_update'),
),
);
}
/**
* Implements hook_menu().
*
* Provides a menu entry which explains what the module does.
*/functionaction_example_menu() {
$items['examples/action_example'] = array(
'title' => 'Action Example',
'description' => 'Provides a basic information page.',
'page callback' => '_action_example_page',
'access callback' => TRUE,
);
return$items;
}
/**
* A simple page to explain to the developer what to do.
*/function_action_example_page() {
returnt("The Action Example provides three example actions which can be configured on the <a href='@actions_url'>Actions configuration page</a> and assigned to triggers on the <a href='@triggers_url'>Triggers configuration page</a>.", array('@actions_url' => url('admin/config/system/actions'), '@triggers_url' => url('admin/structure/trigger/node')));
}
/**
* Action function for action_example_basic_action.
*
* This action is not expecting any type of entity object, and can be used with
* any trigger type or any event.
*
* @param $entity
* An optional entity object.
* @param $context
* Array with parameters for this action: depends on the trigger.
*
* @see action_example_action_info()
*/functionaction_example_basic_action(&$entity, $context = array()) {
//
// In this case we are ignoring the entity and the context. This case of
// action is useful when your action does not depend on the context, and
// the function must do something regardless the scope of the trigger.
// Simply announces that the action was executed using a message.
drupal_set_message(t('action_example_basic_action fired'));
watchdog('action_example', 'action_example_basic_action fired.');
}
/**
* Action function for action_example_unblock_user_action.
*
* This action is expecting an entity object user, node or comment. If none of
* the above is provided (because it was not called from an user/node/comment
* trigger event, then the action will be taken on the current logged in user.
*
* Unblock an user. This action can be fired from different trigger types:
* - User trigger: this user will be unblocked.
* - Node/Comment trigger: the author of the node or comment will be unblocked.
* - Other: (including system or custom defined types), current user will be
* unblocked. (Yes, this seems like an incomprehensible use-case.)
*
* @param $entity
* An optional user object (could be a user, or an author if context is
* node or comment)
* @param $context
* Array with parameters for this action: depends on the trigger. The context
* is not used in this example.
*/functionaction_example_unblock_user_action(&$entity, $context = array()) {
// First we check that entity is a user object. If this is the case, then this
// is a user-type trigger.
if (isset($entity->uid)) {
$uid = $entity->uid;
}
elseif (isset($context['uid'])) {
$uid = $context['uid'];
}
// If neither of those are valid, then block the current user.
else {
$uid = $GLOBALS['user']->uid;
}
$account = user_load($uid);
$account = user_save($account, array('status' => 1));
watchdog('action_example', 'Unblocked user %name.', array('%name' => $account->name));
drupal_set_message(t('Unblocked user %name', array('%name' => $account->name)));
}
/**
* Form function for action_example_node_sticky_action.
*
* Since we defined action_example_node_sticky_action as 'configurable' => TRUE,
* this action requires a configuration form to create/configure the action.
* In this circumstance, Drupal will attempt to call a function named by
* combining the action name (action_example_node_sticky_action) and _form, in
* this case yielding action_example_node_sticky_action_form.
*
* In Drupal, actions requiring creation and configuration are called 'advanced
* actions', because they must be customized to define their functionality.
*
* The 'action_example_node_sticky_action' allows creating rules to promote and
* set sticky content created by selected users on certain events. A form is
* used to configure which user is affected by this action, and this form
* includes the standard _validate and _submit hooks.
*//**
* Generates settings form for action_example_node_sticky_action().
*
* @param $context
* An array of options of this action (in case it is being edited)
*
* @return array $form
*
* @see action_example_action_info()
*/functionaction_example_node_sticky_action_form($context) {
/*
* We return a configuration form to set the requirements that will
* match this action before being executed. This is a regular Drupal form and
* may include any type of information you want, but all the fields of the
* form will be saved into the $context variable.
*
* In this case we are promoting all content types submitted by this user, but
* it is possible to extend these conditions providing more options in the
* settings form.
*/$form['author'] = array(
'#title' => t('Author name'),
'#type' => 'textfield',
'#description' => t('Any content created, presaved or updated by this user will be promoted to front page and set as sticky.'),
'#default_value' => isset($context['author']) ? $context['author'] : '',
);
// Verify user permissions and provide an easier way to fill this field.
if (user_access('access user profiles')) {
$form['author']['#autocomplete_path'] = 'user/autocomplete';
}
// No more options, return the form.
return$form;
}
/**
* Validates settings form for action_example_node_sticky_action().
* Verifies that user exists before continuing.
*/functionaction_example_node_sticky_action_validate($form, $form_state) {
if (! $account = user_load_by_name($form_state['values']['author']) ) {
form_set_error('author', t('Please, provide a valid username'));
}
}
/**
* Submit handler for action_example_node_sticky_action.
*
* Returns an associative array of values which will be available in the
* $context when an action is executed.
*/functionaction_example_node_sticky_action_submit($form, $form_state) {
returnarray('author' => $form_state['values']['author']);
}
/**
* Action function for action_example_node_sticky_action.
*
* Promote and set sticky flag. This is the special action that has been
* customized using the configuration form, validated with the validation
* function, and submitted with the submit function.
*
* @param $node
* A node object provided by the associated trigger.
* @param $context
* Array with the following elements:
* - 'author': username of the author's content this function will promote and
* set as sticky.
*/functionaction_example_node_sticky_action($node, $context) {
if (function_exists('dsm')) {
dsm($node, 'action_example_node_sticky_action is firing. Here is the $node');
dsm($context, 'action_example_node_sticky_action is firing. Here is the $context');
}
// Get the user configured for this special action.
$account = user_load_by_name($context['author']);
// Is the node created by this user? then promote and set as sticky.
if ($account->uid == $node->uid) {
$node->promote = NODE_PROMOTED;
$node->sticky = NODE_STICKY;
watchdog('action', 'Set @type %title to sticky and promoted by special action for user %username.', array('@type' => node_type_get_name($node), '%title' => $node->title, '%username' => $account->name));
drupal_set_message(t('Set @type %title to sticky and promoted by special action for user %username.', array('@type' => node_type_get_name($node), '%title' => $node->title, '%username' => $account->name)));
}
}
/**
* @} End of "defgroup action_example".
*/