interface RulesEventHandlerInterface in Rules 7.2

Interface for handling rules events.

Configurable events (i.e. events making use of settings) have a custom event suffix, which gets appended to the base event name. The configured event name of, e.g. the event for viewing an article node, would be node_view--article, whereas "node_view" is the base event name and "article" the event suffix as returned from RulesEventHandlerInterface::getEventNameSuffix(). The event suffix is generated based upon the event settings and must map to this settings, i.e. each set of event settings must always generate the same suffix. For a configurable event to be invoked, rules_invoke_event() has to be called with the configured event name, e.g.

rules_invoke_event('node_view--' . $node->type, $node, $view_mode);

If the event settings are optional, both events have to be invoked whereas usually the more general event is invoked last. E.g.:

rules_invoke_event('node_view--' . $node->type, $node, $view_mode);
rules_invoke_event('node_view', $node, $view_mode);

Rules event handlers have to be declared using the 'class' key in hook_rules_event_info(), or may be discovered automatically, see rules_discover_plugins() for details.

Hierarchy

• interface \RulesEventHandlerInterface

See also

RulesEventHandlerBase

RulesEventDefaultHandler

File

includes/rules.event.inc, line 38

Contains event handler interface and base classes.

interface RulesEventHandlerInterface {

  /**
   * Constructs the event handler.
   *
   * @param string $event_name
   *   The base event string.
   * @param array $info
   *   The event info of the given event.
   */
  public function __construct($event_name, $info);

  /**
   * Sets the event settings.
   *
   * @param array $settings
   *   An array of settings to set.
   *
   * @return RulesEventHandlerInterface
   *   The handler itself for chaining.
   */
  public function setSettings(array $settings);

  /**
   * Gets the event settings.
   *
   * @return array
   *   The array of settings.
   */
  public function getSettings();

  /**
   * Returns an array of default settings.
   *
   * @return array
   *   The array of default settings.
   */
  public function getDefaults();

  /**
   * Returns a user-facing summary of the settings.
   *
   * @return string
   *   The summary in HTML, i.e. properly escaped or filtered.
   */
  public function summary();

  /**
   * Builds the event settings form.
   *
   * @param array $form_state
   *   An associative array containing the current state of the form.
   *
   * @return array
   *   The form structure.
   */
  public function buildForm(array &$form_state);

  /**
   * Validate the event settings independent from a form submission.
   *
   * @throws RulesIntegrityException
   *   In case of validation errors, RulesIntegrityExceptions are thrown.
   */
  public function validate();

  /**
   * Extract the form values and update the event settings.
   *
   * @param array $form
   *   An associative array containing the structure of the form.
   * @param array $form_state
   *   An associative array containing the current state of the form.
   */
  public function extractFormValues(array &$form, array &$form_state);

  /**
   * Returns the suffix to be added to the base event named based upon settings.
   *
   * If event settings are used, the event name Rules uses for the configured
   * event is {EVENT_NAME}--{SUFFIX}.
   *
   * @return string
   *   The suffix string. Return an empty string for not appending a suffix.
   */
  public function getEventNameSuffix();

  /**
   * Returns info about the variables provided by this event.
   *
   * @return array
   *   An array of provided variables, keyed by variable names and with the
   *   variable info array as value.
   */
  public function availableVariables();

  /**
   * Returns the base name of the event the event handler belongs to.
   *
   * @return string
   *   The name of the event the event handler belongs to.
   */
  public function getEventName();

  /**
   * Returns the info array of the event the event handler belongs to.
   *
   * @return string
   *   The info array of the event the event handler belongs to.
   */
  public function getEventInfo();

}

Members

Name	Modifiers	Type	Description	Overrides
RulesEventHandlerInterface::availableVariables	public	function	Returns info about the variables provided by this event.	1
RulesEventHandlerInterface::buildForm	public	function	Builds the event settings form.	2
RulesEventHandlerInterface::extractFormValues	public	function	Extract the form values and update the event settings.	1
RulesEventHandlerInterface::getDefaults	public	function	Returns an array of default settings.	2
RulesEventHandlerInterface::getEventInfo	public	function	Returns the info array of the event the event handler belongs to.	1
RulesEventHandlerInterface::getEventName	public	function	Returns the base name of the event the event handler belongs to.	1
RulesEventHandlerInterface::getEventNameSuffix	public	function	Returns the suffix to be added to the base event named based upon settings.	2
RulesEventHandlerInterface::getSettings	public	function	Gets the event settings.	1
RulesEventHandlerInterface::setSettings	public	function	Sets the event settings.	1
RulesEventHandlerInterface::summary	public	function	Returns a user-facing summary of the settings.	2
RulesEventHandlerInterface::validate	public	function	Validate the event settings independent from a form submission.	1
RulesEventHandlerInterface::__construct	public	function	Constructs the event handler.	1