How To Create A Custom Rules Action

This post should give a quick example on how to write the code to create your own custom actions for Drupals' Rules module. Writing your own plugins for rules (events, conditions or actions) can give you enormous benefits later, when you start to reuse them throughout the site or even port them on other Drupal sites.

We will be creating an action, which will provide a hashed string. In order to create this string we need to pass some parameters to php's hash function like a source string, a list with possible algorithms to choose and an output length. These parameters will be configurable through Rules' backend. So let's dive in.

First you need to create a basic custom module in your Drupal installation. The one I have in my custom environment is called "my_module".

You don't need anything special in your "my_module.info" or "my_module.module" files, but there has to be a file called "my_module.rules.inc", which will hold the code for your rules' action. Create it and add following code to it:

<?php
 
/**
 * Implement hook_rules_action_info().
 */
function my_module_rules_action_info() {
  return array(
    'my_module_rules_action_create_hashed_string' => array(
      'label' => t('Create hashed string'),
      'group' => t('Custom'),
      'parameter' => array(
        'string' => array(
          'type' => 'text',
          'label' => t('String to be hashed'),
          'description' => t('Enter a value for a string that will be hashed using the md5 hash-algorithm.'),
        ),
        'length' => array(
          'type' => 'integer',
          'label' => t('The length of the returned string'),
          'description' => t('Enter a number for the length of the hashed string that will be created.'),
        ),
        'algorithm' => array(
          'type' => 'text',
          'label' => t('Algorithm'),
          'description' => t('Select a hash algorithm.'),
          'options list' => 'my_module_algorithm_options',
          'restriction' => 'input',
        ),
      ),
      'provides' => array(
        'hashed_string' => array(
          'type' => 'text',
          'label' => t('Hashed string'),
        ),
      ),
    ),
  );
}
 
// A helper function to provide us with a list of algorithms
function my_module_algorithm_options() {
  $algorithms = array();
 
  $algorithms['md4'] = t('md4');
  $algorithms['md5'] = t('md5');
 
  return $algorithms;
}
 
// This callback creates the hashed string by using the parameters provided through rules' UI
function my_module_rules_action_create_hashed_string($string, $length, $algorithm) {
  if ($length <= 0) {
    // For anything below or equal zero lets return the default value.
    $string = hash('md5', $string);
  } else {
    $string = substr(hash($algorithm, $string), 0, $length);
  }
 
  return array(
    'hashed_string' => $string,
  );
}

Here we implement initially "hook_rules_action_info" and add our own action to it. Our action is an associative array keyed with the name of the callback that will return our value (in this case a hashed string). Inside it we give our action a label and put it in a group ("Custom"). The next part of this array is an associative array itself, keyed with "parameter". Inside it we describe our 3 parameters, which will be passed to the action callback. Note that the "algorithm" parameter has an entry with the key "options list" which points to a helper function ("my_module_algorithm_options") to keep the code more lean.

The last part of the array is another associative array keyed with "provides". This key tells Rules what the machine name of the provided variable is, among with giving it some additional data like type or label. You can use this provided variable in latter actions of your rule now!

The last part of the code is the action callback. Only thing to note here is that we return the whole string returned by the hash-function, when the value of $length is below or equal to 0.

Clear your cache in order for Drupal to register the code you added and the new action should appear now:

custom_action_form.jpg

In order to see it's working I've added a "Show a message on the site"-action which shows the provided hashed string when we're looking at a node page:

show_hashed_string_message.jpg

That's it with this simple example! Please leave a comment if there is anything more that comes to mind. Thanks!

Comments

sri (not verified)

its a meaningful example ..but when i create a content then after saving it's not showing hash key, while when we debug like (debug($string )in 'csrule_rules_action_create_hashed_string' function) it's showing hash key...plz help

dimitar

I don't quite get what you mean, but you probably think that this should replace yout node title. It doesn't - it simply generates a hash string from it. What you can do in this case is use this provided variable and set the node title to it through Rules' "Set a data value"-action. Hope this helps.

Add new comment