action_example.module

<?php
/**
 * @file
 * Hook implementations for the Action Example module.
 */

/**
 * @defgroup action_example Example: Action
 * @ingroup examples
 * @{
 * This example demonstrates how to create actions.
 *
 * Actions are a feature that allows some programming without using PHP. Using
 * the appropriate action in a specific event, a site administrator can add new
 * functionality.
 *
 * Examples are:
 *  - Displaying a message after a user has logged in
 *  - Displaying a message after a node has been deleted
 *  - Unblocking a user if selected in a Views list
 *
 * In Backdrop core, actions are mainly run by adding them to bulk operations
 * executed on Views lists, although modules may also trigger actions by calling
 * actions_execute().
 *
 * Actions are very often grouped by functionality: user, node, taxonomy. When
 * actions are grouped, it is because they expect the same arguments.
 *
 * 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; they can be used on every available trigger.
 *
 * What are good candidates to be triggers?
 * Any function can be a trigger, as long as it has the code to call the action,
 * but to make Backdrop more extensible, you will find hooks 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 shows how to create actions. We are providing three actions:
 *
 * - A generic action that can be used in any trigger, which is the most basic
 *   example of an action
 * - A user action
 * - A node action
 *
 * For this module, the generic action will be triggered by executing a
 * submission handler in a form. The Node and User actions will be triggered
 * from a Views bulk operations form.
 */

/**
 * 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
 * the modulename_description_action convention), 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 end in "_action" to be an action.
 *
 * 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 it is enough for a basic example. Type is set to system, so users won't
 *   be confused about the action scope (expecting a node, user, or any other
 *   object).
 * - action_example_unblock_user_action: Unblocks a user.
 * - action_example_node_unpublish_action: In this example action, the action
 *   will unpublish only nodes created by the logged-in user.
 *
 * We return an associative array of action descriptions. The keys of the array
 * are the names of the action functions; 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
 *   like '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 t().
 * - 'callback': (Optional) A function name that will execute the action if the
 *   name of the action differs from the function name.
 * - 'file': (Optional) The relative path from the module's directory for a file
 *   that contains the callback function.
 *
 * @see hook_action_info()
 */
function action_example_action_info() {
  return array(
    'action_example_basic_action' => array(
      'label' => t('Action Example: A basic example action that does nothing'),
      'type' => 'system',
    ),
    'action_example_unblock_user_action' => array(
      'label' => t('Action Example: Unblock a user'),
      'type' => 'user',
    ),
    'action_example_node_unpublish_action' => array(
      'type' => 'node',
      'label' => t('Action Example: Unpublish node if created by logged-in user'),
      'callback' => 'action_example_node_unpublish_callback',
    ),
  );
}


/**
 * Implements hook_menu().
 *
 * Provides a menu entry which explains what the module does.
 */
function action_example_menu() {
  $items['examples/action_example'] = array(
    'title'           => 'Action Example',
    'description'     => 'Provides a basic information page.',
    'page callback'   => '_action_example_page',
    'access callback' => TRUE,
  );
  $items['examples/action_example/basic'] = array(
    'title'           => 'Basic Action Example',
    'description'     => 'Provides a page to execute a basic action.',
    'page callback'   => 'backdrop_get_form',
    'page arguments'   => array('action_example_basic_action_form'),
    'access callback' => TRUE,
  );
  return $items;
}


/**
 * A simple page to explain to the developer what to do.
 */
function _action_example_page() {

  $markup = t('The Action Example provides three example actions. The Basic Action is executed by a simple form. The User and Node actions are demonstrated using a sample Bulk Operations View.<br/>Create at least one user and one node to use the Node and User actions.');

  $list[] = l(t('Basic Action'), 'examples/action_example/basic');
  $list[] = l(t('Node Action'), 'examples/ajax_example/actions-example-node-list');
  $list[] = l(t('User Action'), 'examples/ajax_example/actions-example-user-list');

  $variables['items'] = $list;
  $variables['type'] = 'ul';
  $markup .= theme('item_list', $variables);

  return $markup;
}

/**
 * Action function for action_example_basic_action.
 *
 * This action is not expecting any type of entity object.
 *
 * @param object $entity
 *   An optional entity object.
 * @param array $context
 *   Array with parameters for this action.
 *
 * @see action_example_action_info()
 */
function action_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.
  backdrop_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 a user/node/comment
 * trigger event, then the action will be taken on the current logged-in user.
 *
 * Unblock a 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 object $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. The context
 *   is not used in this example.
 */
function action_example_unblock_user_action(&$entity, $context = array()) {
  // If the entity is a user object, 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, block the logged-in user.
  else {
    $uid = $GLOBALS['user']->uid;
  }
  $account = user_load($uid);

  $account->status = 1;
  $account->save();
  watchdog('action_example', 'Unblocked user %name.', array('%name' => $account->name));
  backdrop_set_message(t('Unblocked user %name', array('%name' => $account->name)));
}

/**
 * Action function for action_example_node_sticky_action.
 *
 * Unpublish a node.
 *
 * @param object $node
 *   A node object provided by the associated trigger.
 * @param array $context
 *   Array with parameters for this action: depends on the trigger. The context
 *   is not used in this example.
 */
function action_example_node_unpublish_callback($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');
  }
  global $user;
  // Get the logged-in user.
  $account = user_load($user->uid);
  // Is the node created by this user? Unpublish it.
  if ($account->uid == $node->uid) {
    $node->status = 0;
    $node->save();
    watchdog('action',
      'Set @type %title unpublished.',
        array(
          '@type' => node_type_get_name($node),
          '%title' => $node->title,
        )
    );
    backdrop_set_message(
      t('Set @type %title unpublished.',
        array(
          '@type' => node_type_get_name($node),
          '%title' => $node->title,
        )
      )
    );
  }
}

/**
 * Form to display the basic action.
 */
function action_example_basic_action_form($form, &$form_state) {
  $form = array();
  $form['intro'] = array(
    '#type' => 'markup',
    '#markup' => t("<div>Demonstrates a basic action.</div>"),
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Execute'),
  );

  return $form;
}

function action_example_basic_action_form_submit($form, &$form_state) {
  actions_execute('action_example_basic_action', NULL, $context);
}

 /**
 * Implements hook_config_info().
 */
function action_example_config_info() {
  $prefixes['views.view.actions_example_node_list'] = array(
    'label' => t('Action Example sample node View'),
    'group' => t('Configuration'),
  );
  $prefixes['views.view.actions_example_user_list'] = array(
    'label' => t('Action Example sample user View'),
    'group' => t('Configuration'),
  );
  return $prefixes;
}

/**
 * @} End of "defgroup action_example".
 */