--- action_example/CHANGELOG.txt
+++ action_example/CHANGELOG.txt
@@ -0,0 +1,2 @@
+# $Id$
+

--- action_example/action_example.info
+++ action_example/action_example.info
@@ -0,0 +1,9 @@
+; $Id$
+
+name = Action example
+description = An example showing how a module can provide actions that can be associated to triggers.
+package = Example modules
+core = 7.x
+dependencies[] = trigger
+files[] = action_example.module
+files[] = action_example.test

--- action_example/action_example.module
+++ action_example/action_example.module
@@ -0,0 +1,361 @@
+<?php
+// $Id$
+
+/**
+ * @file
+ * Action definition example module.
+ *
+ * Triggers and actions are a pair of special-purpose functions 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 able to enqueue actions. The trigger module
+ * provides the interface allowing us to associate certain actions with certain
+ * triggers.
+ *
+ * Actions are the functions intended 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 some 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 to 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 wich which extends the capabilities of User triggers, even if
+ *   associated to 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:
+ *
+ * @todo this is a drupal 6 link
+ * @link http://drupal.org/node/172152 Writing Actions @endlink
+ *
+ * @todo this is a drupal 6 link
+ * @link http://drupal.org/node/199254 Triggers and Actions in Drupal 7 @endlink
+ *
+ * @see hook_action_info()
+ */
+
+/**
+ * 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.
+ *
+ * This is the description of the actions we are passing to hook_action_info()
+ *
+ * - action_example_basic_action: this action is a dummy function, that 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 inmediatelly in the list of action under the menu entry:
+ *   'admin/config/system/actions'
+ *
+ * -
+ *
+ * - 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
+ *   exists by default and it has to be created first. This is called in Drupal
+ *   'Advanced actions', actions that require configuration or customization.
+ *   In this example action, the action will Promote and set Sticky Nodes when
+ *   they are presaved, inserted or updated, but only for certain user. As an
+ *   advanced action, it first needs to be created in the actions management
+ *   page (admin/config/system/actions). At the bottom a selection list will
+ *   show a list of advanced actions that now 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'.
+ *   - '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 a _validate function.
+ *   - 'triggers': An array of the events (that is, hooks) 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 for the "presave" hook, in which case a dependent "save"
+ *       action should NOT be invoked.
+ *
+ */
+function action_example_action_info() {
+  return array(
+    'action_example_basic_action' => array(
+      'label' => t('A basic example action that does Nothing'),
+      'type' => 'system',
+      'configurable' => FALSE,
+      'triggers' => array('any'),
+    ),
+    'action_example_unblock_user_action' => array(
+      'label' => t('Unblock an user'),
+      'type' => 'user',
+      'configurable' => FALSE,
+      'triggers' => array('any'),
+    ),
+    'action_example_node_sticky_action' => array(
+      'type' => 'node',
+      'label' => t('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'),
+    ),
+  );
+}
+
+/*
+ * Most basic action.
+ *
+ * This action is not expecting any type of entity object, and can be used with
+ * any trigger type or any event.
+ */
+
+/**
+ * Basic example action.
+ *
+ * @param $entity
+ *   An optional entity object.
+ * @param array $context
+ *   Array with parameters for this action: depends on the trigger.
+ *
+ * @ingroup actions
+ */
+function action_example_basic_action(&$entity, $context = array()) {
+  /**
+   * In this case we are ignoring the entity and the context. This case of 
+   * action is usefull when your action does not depend on the context, and 
+   * the function must do something regardless the scope of the trigger.
+   * 
+   * Simply mark the action as executed using a watchdog message.
+   */
+	
+  watchdog('action_example', 'example basic action fired.');
+}
+
+/*
+ * A complex action for different trigger types.
+ *
+ * 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.
+ *
+ * @param $entity
+ *   An optional user object (could be a user, or an author if context is
+ *   node or comment)
+ * @param array $context
+ *   Array with parameters for this action: depends on the trigger.
+ * 
+ * @ingroup actions
+ */
+function action_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));
+}
+
+/*
+ * A complex action using customization.
+ *
+ * The next action requires a configuration form to create the final 'action'.
+ * In Drupal these are called 'Advanced actions', because they can be customized
+ * to alter default functionality.
+ *
+ * The 'action_example_node_sticky_action' allow creating rules to promote and
+ * set sticky content created by selected users on certain events. A form is
+ * used to configure wich is the user affected by this action, and this form
+ * includes the regular _validate and _submit hooks as any other form un Drupal.
+ */
+
+
+/**
+ * Generates settings form for action_example_node_sticky_action().
+ *
+ * @param array $context
+ *  An array of options of this action (in case it is being edited)
+ * @return array $form
+ *
+ */
+function action_example_node_sticky_action_form($context) {
+	/*
+	 * We should 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, instead of Drupal variables
+	 * or using a custom handler.
+	 *
+	 * In this case we are promoting all content types submited 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;
+}
+
+/**
+ * Validate settings form for action_example_node_sticky_action().
+ * Verify that user exists before continuing.
+ */
+function action_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'));
+  }
+}
+
+/**
+ * Saves settings form for action_example_node_sticky_action().
+ * Handle the action configuration form submission.
+ */
+function action_example_node_sticky_action_submit($form, $form_state) {
+  return array('author' => $form_state['values']['author']);
+}
+
+/**
+ * Promote and set sticky flag action. This is the special action that has been
+ * customized using the configuration form.
+ *
+ * @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.
+ *
+ * @ingroup actions
+ */
+function action_example_node_sticky_action($node, $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));
+  }
+}
+
+
+
+
+
+
+
+
+/**
+ * Optional usage of hook_action_info_aler()
+ *
+ * This function is not required to write your own actions, but it may be
+ * useful when you want to alter existing actions.
+ *
+ */
+
+/**
+ * Implements hook_action_alter().
+ *
+ * Call hook_action_alter to change an existing action. As mentioned earlier,
+ * this hook is not required to create custom actions, and should only be used
+ * to alter existing actions.
+ *
+ * In this example implementation a little change is done to the existing action
+ * provided by core: 'node_unpromote_action'. This action removes content from
+ * the front page.
+ *
+ * @param array $actions
+ *  Array of action information returned by hook_action_info() implementations.
+ *
+ * @see hook_action_info()
+ */
+function action_example_action_info_alter(&$actions) {
+  // Make a simple change to an existing core action, altering the label
+  // "Remove content from front page" to our custom label "Demote content"
+  $actions['node_unpromote_action']['label'] = t('Demote content');
+}

--- action_example/action_example.test
+++ action_example/action_example.test
@@ -0,0 +1,27 @@
+<?php
+// $Id$
+
+/**
+ * @file
+ * test file for trigger_example module.
+ */
+
+/**
+ * Default test case for the trigger_example module.
+ */
+class ActionExampleTestCase extends DrupalWebTestCase {
+
+  public static function getInfo() {
+    return array(
+      'name' => 'Action example',
+      'description' => 'Perform various tests on action_example module.' ,
+      'group' => 'Examples',
+    );
+  }
+
+  function setUp() {
+    parent::setUp('trigger', 'action_example');
+  }
+
+
+}