interface.event.php

<?php

/**
 * @package interface
 */
/**
 * This interface describes the minimum a new Event type needs to
 * provide to be able to be used by Symphony
 *
 * @since Symphony 2.3.1
 */
interface iEvent
{
    /**
     * Returns the human readable name of this event type. This is
     * displayed in the event selection options.
     *
     * @return string
     */
    public static function getName();

    /**
     * Returns the absolute path to the template that this template will
     * use to save instances of this event in the `events` folder.
     *
     * @return string
     */
    public static function getTemplate();

    /**
     * Returns the `__CLASS__` on the provided event, this is often
     * used as a way to namespace settings in forms and provide a unique
     * handle for this event type
     *
     * @return string
     */
    public static function getSource();

    /**
     * This function returns all the settings of the current event
     * instance.
     *
     * @return array
     *  An associative array of settings for this event where the
     *  key is `getClass` and the value is an associative array of settings,
     *  key being the setting name, value being, the value
     */
    public function settings();

    /**
     * This function is invoked by the Event Editor and allows this
     * event to provide HTML so that it can be created or edited.
     * It is expected that this function will also handle the display
     * of error messages.
     *
     * @see settings()
     * @param XMLElement $wrapper
     *  An XMLElement for the HTML to be appended to. This is usually
     *  `AdministrationPage->Form`.
     * @param array $errors
     *  If there are any errors, this variable will be an associative
     *  array, key being the setting handle.
     * @param array $settings
     *  An associative array of settings. This may be null on create, but
     *  will be populated with the event's settings on edit using
     *  `settings()`.
     * @param string $handle
     *  If the event already exists (so it's being edited), the handle
     *  of the event will be passed to this function.
     * @return
     */
    public static function buildEditor(XMLElement $wrapper, array &$errors = array(), array $settings = null, $handle = null);

    /**
     * Given an array of settings, validate them, adding any errors
     * to the `$errors` variable which is passed by reference. `$errors`
     * should be formatted as an associative array
     *
     * @param array $settings
     *  An associative array of settings
     * @param array $errors
     *  Passed as an empty array, can be populated with any validation errors
     * @return boolean
     *  true if the event is valid, false otherwise.
     *  If false it is expected that `$errors` are populated.
    */
    public static function validate(array &$settings, array &$errors);

    /**
     * Given the settings and any existing event parameters, return the contents
     * of this event that can be saved to the filesystem.
     *
     * @param array $fields
     *  An associative array of settings for this event, where the key
     *  is the name of the setting. These are user defined through the event
     *  Editor.
     * @param array $parameters
     *  An associative array of parameters for this event, where the key
     *  is the name of the parameter.
     * @param string $template
     *  The template file, which has already been altered by Symphony to remove
     *  any named tokens (ie. `<!-- CLASS NAME -->`).
     * @return string
     *  The completed template, ready to be saved.
     */
    public static function prepare(array $fields, array $parameters, $template);

    /**
     * Return an associative array of meta information about this event such
     * creation date, who created it and the name.
     *
     * @return array
     */
    public static function about();

    /**
     * The load functions determines whether an event will be executed or not
     * by comparing the Event's action with the `$_POST` data. This function will
     * be called every time a page is loaded that an event is attached too. If the
     * action does exist, it typically calls the `__trigger()` method, otherwise void.
     *
     * @return mixed
     *  XMLElement with the event result or void if the action did not match
     */
    public function load();

    /**
     * This function actually executes the event, and returns the result of the
     * event as an `XMLElement` so that the `FrontendPage` class can add to
     * a page's XML.
     *
     * @return XMLElement
     *  This event should return an `XMLElement` object.
     */
    public function execute();
}