[Summary view] [Print] [Text view]

   1  $Id: API.txt,v 1.1.2.5 2010/07/04 17:44:41 yhahn Exp $
   2  
   3  Features 1.x API for Drupal 6.x
   4  -------------------------------
   5  This file contains documentation for two audiences: site builders interested in
   6  creating and managing features and module developers interested in integrating
   7  with the features module.
   8  
   9  
  10  Terminology
  11  -----------
  12  - A **feature module** is a Drupal module that contains the `feature` key in its
  13  `.info` file. This array describes the components that should be managed by
  14  Features within the module.
  15  
  16  - A **component** is a configuration object that can be exported. Examples: a
  17  view, content type or CCK field instance.
  18  
  19  - A **machine name** is a string identifier for a specific type of component and
  20  should be unique within a single Drupal site. It should not be a numerically
  21  generated serial id.
  22  
  23  - An **exportable** component is one that can be used solely from a default hook
  24  in code and without an instance in the database. For example, a view that lives
  25  in code does not need an entry in the database in order to be used.
  26  
  27  - A **faux-exportable** component is one that must exist in the database in
  28  order to be used. Any exports of this component are used to create or
  29  synchronize entries in the database that share the same machine name.
  30  
  31  
  32  ### Component states
  33  
  34  Features provides some infrastructure to determine the state of components on
  35  the site. To determine the state of a component Features keeps track of three
  36  things using an md5 hash of
  37  
  38  - current code for the component. This is the configuration as actually
  39  represented in code by a given feature.
  40  
  41  - the most recent prior code state that differs from the current code state. For
  42  example, if an `svn update` changes the configuration of a view, this stores the
  43  code state *prior* to the update.
  44  
  45  - The "normal" component state. This is the configuration represented by the
  46  component as stored in the database or the default component (with any changes
  47  introduced by `drupal_alter()`) if no database override exists.
  48  
  49  Using these three values, Features determines a component to be in one of the
  50  following five states:
  51  
  52  - **Default** (`FEATURES_DEFAULT`) The object has no database entry or the
  53  database entry matches the state of the component in code. This should be the
  54  default state of components after installing a feature. Updating the component
  55  can be done by altering the code definition directly.
  56  
  57  - **Overridden** (`FEATURES_OVERRIDDEN`) The code remains constant but the
  58  database object does not match the state of the component in code. Changes must
  59  be reverted before the component can be updated from code.
  60  
  61  - **Needs review** (`FEATURES_NEEDS_REVIEW`) The previous code state, database
  62  state, and current code state all differ. This occurs most commonly when a user
  63  changes one of her components and then pulls updates to her codebase. Since
  64  there is no way to tell whether the code state or the database state is more
  65  recent/valid, user input is necessary to resolve this state.
  66  
  67  - **Rebuildable** (`FEATURES_REBUILDABLE`) This state only applies to
  68  **faux-exportables** and indicates that the database component must and can be
  69  safely updated from the code definition. The database entry does not match the
  70  current code state but does match the previous code state. Features assumes that
  71  in this scenario the user has made no substantive changes and the component can
  72  be updated automatically.
  73  
  74  - **Rebuilding** (`FEATURES_REBUILDING`) This state is rarely seen and only
  75  applies to **faux-exportables.** This state is shown when a
  76  `FEATURES_REBUILDABLE` component is *currently* being synced to the database.
  77  Usually this operation is very fast and short lived. However, if the operation
  78  is interrupted (e.g. the server goes down) this state will be seen until the
  79  rebuild locking semaphore is cleared.
  80  
  81  
  82  How a feature is generated
  83  --------------------------
  84  At a high level Features writes the code in a feature module using the following
  85  steps:
  86  
  87  1. An `.info` file describing the components that should be included in a
  88  Feature is generated. It is either read from an existing feature or generated
  89  through the Features UI.
  90  
  91  2. Features converts the info file into an `$export` array which contains a list
  92  of elements to be exported. Each component type is given a chance to add to the
  93  export list as well as request that *other* components be given a second chance
  94  to add to the `$export` array.
  95  
  96  3. If any additional components have been queued up in the `$pipe` we repeat
  97  step 2 for each of the queued component types.
  98  
  99  4. Once a full `$export` array is populated each component renders items from
 100  the `$export` array to PHP code as a exportable defaults hook.
 101  
 102  5. Finally, Features writes the code into files and delivers it as a
 103  downloadable package (UI) or writes it directly to a module directory (drush).
 104  
 105  This workflow makes a variety of things possible:
 106  
 107  ### Add components to a feature
 108  
 109  Add the components to the `features` array in the feature's `.info` file and run
 110  `drush features-update`. The same operation can be performed using the
 111  *Recreate* page in the Features UI.
 112  
 113  ### Remove components from a feature
 114  
 115  Remove the corresponding component lines from the feature's `.info` file and run
 116  `drush features-update`. The same operation can be performed using the
 117  *Recreate* page in the Features UI.
 118  
 119  ### Rename a component
 120  
 121  Rename a component by changing its name in the feature's `.info` file and the
 122  key and name property of the exported object in the appropriate `.inc` file in
 123  the feature. Note that any references in other configuration objects to the
 124  previous name should also be updated.
 125  
 126  
 127  Integrating your module with the Features API
 128  ---------------------------------------------
 129  This section is for developers interested in adding Features-based management
 130  for the configuration objects in their modules. From the perspective of
 131  Features, there are a few different ways that modules store their configuration:
 132  
 133  - In the `variable` table using `variable_set()`. If a module is using variables
 134  for storing configuration, these variable settings can be exported with Features
 135  by using the [Strongarm][1] module.
 136  
 137    **Features integration:** Install the Strongarm module.
 138  
 139  - Using a custom table with a serial ID for identifying configuration objects.
 140  If this is the case, you will need to change your schema to use a string
 141  identifier / machine name for each object.
 142  
 143    **Features integration:** Fix your schema first, then see below.
 144  
 145  - Using a custom table with a machine name identifier and custom exportables
 146  handling (e.g. you have your own defaults hook handling and export generation).
 147  If this is the case, you will need to implement many of the features hooks
 148  yourself.
 149  
 150    **Features integration:** `hook_features_api()`, `hook_features_export()`,
 151  `hook_features_export_render()`, `hook_features_export_options()`,
 152  `hook_features_revert()`.
 153  
 154  - Using a custom table with CTools Export API integration. If this is the case,
 155  Features will automatically have integration with your module. You can implement
 156  any of the Features hooks in order to override the default CTools exportables
 157  integration behavior.
 158  
 159    **Features integration:** Automatically provided. You may implement any of the
 160  Features hooks where you need further customization for your configuration
 161  object.
 162  
 163  If it isn't clear by now, we highly recommend using the [CTools][2] Export API
 164  for adding exportables to your module. Stella has written a [fantastic HOWTO][3]
 165  on using the CTools Export API that can get you started.
 166  
 167  
 168  An overview of Features hooks
 169  -----------------------------
 170  Extensive documentation of the hooks provided by Features is available in
 171  `features.api.php`. This section provides a short overview of each hook and its
 172  role.
 173  
 174  - `hook_features_api()` defines one or more component types that are available
 175  to Features for export and a variety of settings for each type.
 176  - `hook_features_export()` processes a list of components, detecting any
 177  dependencies or further components
 178  - `hook_features_export_options()` provides an array of components that can be
 179  exported for a given type.
 180  - `hook_features_export_render()` renders a set of components to code as a
 181  defaults hook.
 182  - `hook_features_revert()` reverts components of a feature back to their default
 183  state.
 184  - `hook_features_rebuild()` updates faux-exportable components back to their
 185  default state. Only applies to faux-exportables.
 186  
 187  
 188  [1]: http://drupal.org/project/strongarm
 189  [2]: http://drupal.org/project/ctools
 190  [3]: http://civicactions.com/blog/2009/jul/24/using_chaos_tools_module_create_exportables