$Id: API.txt,v 1.1.2.2 2009-03-17 00:59:10 jmiccolis Exp $

Features for Drupal 6.x
API & code concepts documentation

What is a feature? (technical definition)
-----------------------------------------
A feature is a module that contains the 'feature[]' property in its
.info file. This array can be used to store the "components" of a
feature (e.g. views, node types, fields, etc.)

This allows existing modules to be turned into features by hand by
simply adding the components that belong to the feature to the .info
file. It also allows for programmatic updating of code from database
changes and reverting database changes back to code defaults.

hook_features_export()
----------------------
The most critical hook in the Features module that you will need to
use to integrate your module with Features is hook_features_export().
It receives 3 arguments:

hook_features_export($data, &$export, $module_name = '')

$data is an array of identifiers that is specific to the objects /
  structure provided by your module. For example, $data should be an
  array of view names views_features_export(). For node_features_export(),
  $data is an array of content string names. etc.

$export is an export array passed by reference. It has two main keys:
  $export['features'] and $export['dependencies']. You can modify this
  array to alter what components are part of the final feature and what
  module dependencies the feature will require.

$module_name is the name of the module to be exported to. This can be
  useful when updating a module and determining whether a component needs
  to be excluded and instead replaced wth a dependency on another module
  (which might provide that component by default).

In practice, hook_features_export() has 3 tasks:

1.  Determine module dependencies for any of the components passed to it
    e.g. the views implementation iterates over each views' handlers and
    plugins to determine which modules need to be added as dependencies.

2.  Correctly add components to the export array. In general this is usually
    adding all of the items in $data to $export['features']['my_key'], but
    can become more complicated if components are shared between features
    or modules.

3.  Delegating further detection and export tasks to related or derivative
    components.

#3 is a key concept in the Features module. Each export processor can
kickoff further export processors by returning a keyed array where the
key is the next export processor hook to call and value is an array to be
passed to that processor's $data argument. This allows an export process to
start rather simply, at a single object:

  [context]

And then branch out, delegating each level of branching to its
appropriate hook:

  [context]--------+------------+
      |            |            |
    [node]      [block]      [views]
      |
    [CCK]
      |
 [imagecache]

hook_features_export_options()
------------------------------
This hook is optional and lets you provide an FormAPI select $options
array so that users can manually add any components that the Features
autodetection fails to pick up.

hook_features_export_render()
-----------------------------
This hook passes you an array of identifiers (identical in format to
$data) once the $export array has been fully populated. At this stage
you are expected to return actual code that can be placed in a module
that represents your exportable. More on this below...

Exportables
-----------
Features takes advantage of a concept in Drupal that goes by many
names. For our purposes we will call them "Exportables". Exportables
are simply exported definitions or configuration. They have several
key distinguishing features:

1.  They are code, often PHP arrays or objects.

2.  They are not "imported" or inserted into the database but rather
    distinguished from normal user-created structures as "Defaults"
    provided by modules.

3.  They can be overridden by user defined structures, often by
    convention (e.g. objects with the same identifier that exist in
    both code and the database are considered "Overridden").

Modules with exportables are best identified by the presence of a
hook which collects defaults in code and merges them into the set
of usable objects. Examples include: hook_node_type_info(),
hook_views_default_views(), hook_context_default_contexts(), etc.

Adding exportables to your module
---------------------------------
To integrate against features you must first and foremost have an
exportables architecture in your module. If you don't have this, do
this first. The basic requirements for exportables are:

1.  You should use string identifiers (ideally user defined) rather
    than sequenced IDs.

2.  You should have a formal structure for your objects (no purely
    form-based APIs!)

3.  You should have decent API functions, specifically one that
    collects all your usable items at once (e.g. node_get_types()).

Once you have these things, it's very straightforward to add
exportables. If your current collection function looks like this:

  function mymodule_items() {
    $items = array();

    // Load all items from the database
    $result = db_query( ... );
    while ($row = db_fetch_object($result)) {
      ...
    }
    return $items;
  }

You simply need to change it to look like this:

  function mymodule_items() {
    // Collect default items
    $items = module_invoke_all('mymodule_default_items');
    drupal_alter('mymodule_default_items', $items);

    // Load all items from the database
    $result = db_query( ... );
    while ($row = db_fetch_object($result)) {
      ...
      if (!empty($items[$row->id])) {
        // define constants for your storage states
        $row->storage = MYMODULE_OVERRIDDEN;
        $items[$row->id] = $row;
      }
    }
    return $items;
  }

This is essentially the "import" portion of your module's API. Note that
after collecting default items you do not write them to the database. You
may want to use a serialized cache to store collected default items, but
that is the furthest extent to which any DB changes makes sense.

The other portion of your API is exporting objects. This can be as simple
as a form that allows a user to paste a var_export() of your object into
her module's hook_mymodule_default_items().