action_example.module

<?php
/**
 * @file
 * Action definition example module.
 */

/**
 * @defgroup action_example Example: Action
 * @ingroup examples
 * @{
 * Creating actions in Backdrop
 *
 * Actions are Backdrop features allowing some Backdrop programming without
 * using PHP. Using the appropriate action in a specific event, a site
 * administrator can add new functionality.
 *
 * Examples are:
 *  - Display a message after a user has logged in.
 *  - Display a message after a node has been deleted.
 *  - Unblock 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: examples are '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 that they do not require
 * special objects in their contexts, and so 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 (from Backdrop 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 Backdrop. 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.
 *
 * - A User action.
 *
 * - A Node action.
 *
 * For this module, the generic action will be triggered by executing a submit
 * function in a simple form. The Node and User actions will be triggered from
 * a Views bulk operations form.
 *
 * @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
 * Backdrop'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 end in "_action" to be declared as
 * a Backdrop 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 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).
 * - 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, 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.
 * - 'callback': Optional. A function name that will execute the action if the
 *   name of the action differs from the function name.
 * - 'file': Optional. Relative path to a file from the module's directory
 *   that contains the callback function. *
 * @see hook_action_info()
 * @noinspection SpellCheckingInspection
 */
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: depends on the trigger.
 *
 * @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: depends on the trigger. The context
 *   is not used in this example.
 */
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->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? then 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".
 */