function hook_rules_event_info in Rules 7.2

Same name and namespace in other branches

1. 6 rules/rules.api.php \hook_rules_event_info()

Define rules events.

This hook is required in order to add a new rules event. It should be placed into the file MODULENAME.rules.inc, which gets automatically included when the hook is invoked. The module has to invoke the event when it occurs using rules_invoke_event(). This function call has to happen outside of MODULENAME.rules.inc, usually it's invoked directly from the providing module but wrapped by a module_exists('rules') check.

However, as an alternative to implementing this hook, class based event handlers may be provided by implementing RulesEventHandlerInterface. See the interface for details.

Return value

array An array of information about the module's provided rules events. The array contains a sub-array for each event, with the event name as the key. The name may only contain lower case alpha-numeric characters and underscores and should be prefixed with the providing module name. Possible attributes for each sub-array are:

• label: The label of the event. Start capitalized. Required.
• group: A group for this element, used for grouping the events in the interface. Should start with a capital letter and be translated. Required.
• class: (optional) An event handler class implementing the RulesEventHandlerInterface. If none is specified the RulesEventDefaultHandler class will be used. While the default event handler has no settings, custom event handlers may be implemented to to make an event configurable. See RulesEventHandlerInterface.
• access callback: (optional) An callback, which has to return whether the currently logged in user is allowed to configure rules for this event. Access should be only granted, if the user at least may access all the variables provided by the event.
• help: (optional) A help text for rules reaction on this event.
• variables: (optional) An array describing all variables that are available for elements reacting on this event. Each variable has to be described by a sub-array with the possible attributes:
  • label: The label of the variable. Start capitalized. Required.
  • type: The rules data type of the variable. All types declared in hook_rules_data_info() or supported by hook_entity_property_info() may be specified.
  • bundle: (optional) If the type is an entity type, the bundle of the entity.
  • description: (optional) A description for the variable.
  • 'options list': (optional) A callback that returns an array of possible values for this variable as specified for entity properties at hook_entity_property_info().
  • 'skip save': (optional) If the variable is saved after the event has occurred anyway, set this to TRUE. So rules won't save the variable a second time. Defaults to FALSE.
  • handler: (optional) A handler to load the actual variable value. This is useful for lazy loading variables. The handler gets all so far available variables passed in the order as defined. Also see https://www.drupal.org/node/884554. Note that for lazy-loading entities just the entity id may be passed as variable value, so a handler is not necessary in that case.

See also

rules_invoke_event()

Related topics

2 functions implement hook_rules_event_info()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

rules_rules_event_info in ./rules.rules.inc

Implements hook_rules_event_info().

rules_test_rules_event_info in tests/rules_test.rules.inc

Implements hook_rules_event_info().

File

./rules.api.php, line 370

Documentation for hooks provided by the Rules API.

Code

function hook_rules_event_info() {
  $items = array(
    'node_insert' => array(
      'label' => t('After saving new content'),
      'group' => t('Node'),
      'variables' => rules_events_node_variables(t('created content')),
    ),
    'node_update' => array(
      'label' => t('After updating existing content'),
      'group' => t('Node'),
      'variables' => rules_events_node_variables(t('updated content'), TRUE),
    ),
    'node_presave' => array(
      'label' => t('Content is going to be saved'),
      'group' => t('Node'),
      'variables' => rules_events_node_variables(t('saved content'), TRUE),
    ),
    'node_view' => array(
      'label' => t('Content is going to be viewed'),
      'group' => t('Node'),
      'variables' => rules_events_node_variables(t('viewed content')) + array(
        'view_mode' => array(
          'type' => 'text',
          'label' => t('view mode'),
        ),
      ),
    ),
    'node_delete' => array(
      'label' => t('After deleting content'),
      'group' => t('Node'),
      'variables' => rules_events_node_variables(t('deleted content')),
    ),
  );

  // Specify that on presave the node is saved anyway.
  $items['node_presave']['variables']['node']['skip save'] = TRUE;
  return $items;
}