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 theUser
component for an example of how to specify custom functions. Note that this array can be empty as well, see functionhook_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()
andhook_patterns_validate()
are called to format the input and validate against the database;hook_patterns_build()
, andhook_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