Returning an entity from a custom Rules action

Question

I'm new to writing modules and back end dev. I'm trying to write a custom Rules action that takes a list and returns one item from that list to use as a relationship end point.

I've declared the rule here and got it working as far as I can extract one item from the list and put it as a message on screen:

function rules_additions_rules_action_info() {
$actions = array(
    'rules_additions_action_get_next_list_item' => array(
        'label' => t('Get next list item'),
        'group' => t('Data'),
        'parameter' => array(
            'list' => array(
                'type' => 'list',
                'label' => t('Select the current list'),
                ),
            ),
        ),
    );

return $actions;
}

And can do something like this, for example:

function rules_additions_action_get_next_list_item($list) {
    drupal_set_message(t('The item is ' . print_r($list[0], TRUE)), 'status');
}

What I want to be able to do is return that list item as an entity so at the next step in my rule set I can do "Add an item to a list" and select it in the rules UI.

I hope this makes sense.

Thanks in advance.

Answer 1

If you check the rules hook hook_rules_action_info docs, you'll see the provides element:

provides: (optional) An array describing the variables the action provides to the evaluation state with the variable name as key. Each variable has to be described by a sub-array with possible attributes as described afterwards, whereas the name of a parameter needs to be a lowercase, valid PHP variable name.

Usage example from commerce_cart module:

  $actions['commerce_cart_product_add_by_sku'] = array(
    'label' => t('Add a product to the cart'),
    'parameter' => array(
      'user' => array(
        'type' => 'user',
        'label' => t('User'),
        'description' => t('Specify the user whose shopping cart order the product will be added to, typically <em>site:current-user</em>.'),
      ),
      'sku' => array(
        'type' => 'text',
        'label' => t('Product SKU'),
        'description' => t('The SKU of the product to add to the cart.'),
      ),
      'quantity' => array(
        'type' => 'integer',
        'label' => t('Quantity'),
        'default value' => 1,
      ),
      'combine' => array(
        'type' => 'boolean',
        'label' => t('Combine similar items in the cart'),
        'description' => t('If checked, the product will be combined added to an existing similar product line item in the cart by incrementing its quantity.'),
        'default value' => TRUE,
      ),
    ),
    'group' => t('Commerce Cart'),
    'callbacks' => array(
      'execute' => 'commerce_cart_rules_product_add_by_sku',
    ),
    'provides' => array(
      'product_add_line_item' => array(
        'type' => 'commerce_line_item',
        'label' => t('Added product line item'),
      ),
    ),
  );

Note that you need to return an array from your action with the parameters named, for this example, 'product_add_line_item':

// Only return an added line item.
if ($line_item = commerce_cart_product_add_by_id($product->product_id, $quantity, $combine, $uid)) {
  return array('product_add_line_item' => $line_item);
}

So potentially you could provide as many elements as you need in your actions for further actions or rules components.