Writing a component for Patterns 7.x

A Patterns component is very much like a driver software: It is an interface between input data (user input) and the Drupal backend (hardware).

Patterns is shipped with a 'submodule' containing a battery of components already implemented inside the directory patterns_components/components/; these cover the main Drupal core functionalities such as Block, Taxonomy, Menu etc. However, any module can become a Patterns component by implementing the hook_patterns_components and expanding the set of supported components.

Remember to enable the submodule Patterns Components, in order to make them the components available to the Patterns engine.

Patterns hooks

Tasks in a component are modularized. For this reason, a full component can implement from 1 to 10 Patterns hooks. Their purpose, input parameters and return values are thoroughly explained here, however for live examples see the block.inc, system.inc, taxonomy.inc. etc. components inside the patterns/components/ directory.

Static hooks

These hooks are invoked once and results cached.

hook_patterns($data): declares that the module is able to handle pattern configurations, and specifies which tags and forms are supported.
hook_patterns_components(): adds a real path to the list of directories that will be scanned for Patterns components.
hook_patterns_directory(): adds a real path to the list of directories that will be scanned for Patterns files

Engine hooks

The following hooks are invoked when a pattern is run, and are all optional.

hook_patterns_prepare($action, $tag, &$data): checks the input and adds default values. Eventually, it can raise errors which halt further execution of the pattern. At this stage, there should be no look up into the database, which is the task of the next hook.
hook_patterns_validate($action, $tag, &$data): this hooks is similar to the previous one, however, you are working with the prepared data and you are checking against the database.
hook_patterns_callbacks($action, $tag, &$data): returns the array of form ID’s which will be run sequentially. If a value in this array is not present in the form id list returned by hook_patterns(), the value will be treated as a regular callback function and will be called with the ($action, $data) parameters. In this case, the next 3 functions are not called and the Pattern action result is provided by the callback function(s).
hook_patterns_build($action, $form_id, &$data, &$action_state): gets the form data for the action. This can either be just the form values, or it can be the full form_state object.
hook_patterns_params($action, $form_id, &$data &$action_state): returns extra parameters that the form may require.
hook_patterns_cleanup($action, $tag, &$data): performs optional additional operations, after the execution of the action has finished.

In the above list, $action is one of the actions create, modify, delete and $tag is the specific command to execute (e.g. vocabulary, field, etc.).

Return values for the Patterns hooks

hook_patterns(): returns the following array of actions:
```
  $actions['tag1'] = array(
    PATTERNS_INFO => t('Description of this tag'),
    PATTERNS_CREATE => array('form_to_create_tag1', 'form_to_create_tag2'),
    PATTERNS_MODIFY => array('form_to_modify_tag1', 'form_to_modify_tag2'),
    PATTERNS_DELETE => array('form_to_delete_tag1', 'form_to_delete_tag2'),
    PATTERNS_FILES  => $files = array('path/to/my/include.inc'),
    PATTERNS_EXPORT => array( PATTERNS_EXPORT_ALL => 'export_all_tag1'),
  );

  //$actions['tag2'] = ... ;
  return $actions;
```
where 'tag1', 'tag2' etc. namespace the command to execute (e.g. vocabulary, field, etc.). Each tag can specify up three actions: create, modify, delete. Each action is pointing to one or more handler. The handler is usually the name of a form id, but it can also be a custom function. In the latter case, it still needs to be defined as a form handler, since it will receive the input parameters accordingly. See the User component for an example of how to specify custom functions. Note that this array can be empty as well, see function hook_patterns_callbacks.

The PATTERNS_FILES array contains the path to one or more files that should be included in the to perform the operation of the handlers, and that are not included by default by Drupal. Path should be relative to the Drupal root directory. drupal_get_path can be useful here.

The PATTERNS_EXPORT index is optional, and should point to the name(s) of a function(s) that perform the export from the database.
A more exhaustive explanation about automatic exporting for Patterns can be found here.
hook_patterns_build(), hook_patterns_params(), hook_patterns_cleanup() all return the following special associative array:
```
    status: One of [PATTERNS_SUCCESS, PATTERNS_WARN, PATTERNS_ERR]. Required.

    msg: A message.

    result: Any kind of additional data.
```
The function patterns_results() can be used to produce such an array.
hook_patterns_get_arguments: the return value is always an array of extra parameters to be passed to the MODIFY form. In case $loop was set to true, an array of arrays must be returned.

The Patterns hooks execution cycle

hook_patterns() is called independently from the others hooks, which are invoked sequentially to perform an action. A successful chain of execution would look like the following:

returns some form ID’s, the engine do the following for each form ID:

hook_patterns_prepare() and hook_patterns_validate() are called to format the input and validate against the database;
hook_patterns_build(), and hook_patterns_params() are executed to build the form object, and pass in extra parameters, while checking for errors;
hook_patterns_callbacks() may return additional form_ids or function names to be executed;
the form object is submitted (call the Drupal function drupal_form_submit());
hook_patterns_cleanup() is finally called to delete any temporary results that may be left around.

Further details about the execution cycle can be found in the "Pattern Execution" section of the Tour of the code for contributors.
A very simple "patterns_hello_world" module implementing hook_patterns() for a form with two values can also be checkout from GitHub at git://github.com/QScience/patterns_hello_world.git