interface RulesEventHandlerInterface

Same name in other branches
  1. 8.x-3.x src/Core/RulesEventHandlerInterface.php \Drupal\rules\Core\RulesEventHandlerInterface

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

Expanded class hierarchy of RulesEventHandlerInterface

All classes that implement RulesEventHandlerInterface

See also

RulesEventHandlerBase

RulesEventDefaultHandler

File

includes/rules.event.inc, line 38

View source 
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

Title Modifiers Object type Summary 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