You are here

API.txt in Features 7.2

Same filename and directory in other branches
  1. 6 API.txt
  2. 7 API.txt
Features 1.x API for Drupal 7.x
-------------------------------
This file contains documentation for two audiences: site builders interested in
creating and managing features and module developers interested in integrating
with the features module.


Terminology
-----------
- A **feature module** is a Drupal module that contains the `feature` key in its
`.info` file. This array describes the components that should be managed by
Features within the module.

- A **component** is a configuration object that can be exported. Examples: a
view, content type or CCK field instance.

- A **machine name** is a string identifier for a specific type of component and
should be unique within a single Drupal site. It should not be a numerically
generated serial id.

- An **exportable** component is one that can be used solely from a default hook
in code and without an instance in the database. For example, a view that lives
in code does not need an entry in the database in order to be used.

- A **faux-exportable** component is one that must exist in the database in
order to be used. Any exports of this component are used to create or
synchronize entries in the database that share the same machine name.


### Component states

Features provides some infrastructure to determine the state of components on
the site. To determine the state of a component Features keeps track of three
things using an md5 hash of

- current code for the component. This is the configuration as actually
represented in code by a given feature.

- the most recent prior code state that differs from the current code state. For
example, if an `svn update` changes the configuration of a view, this stores the
code state *prior* to the update.

- The "normal" component state. This is the configuration represented by the
component as stored in the database or the default component (with any changes
introduced by `drupal_alter()`) if no database override exists.

Using these three values, Features determines a component to be in one of the
following five states:

- **Default** (`FEATURES_DEFAULT`) The object has no database entry or the
database entry matches the state of the component in code. This should be the
default state of components after installing a feature. Updating the component
can be done by altering the code definition directly.

- **Overridden** (`FEATURES_OVERRIDDEN`) The code remains constant but the
database object does not match the state of the component in code. Changes must
be reverted before the component can be updated from code.

- **Needs review** (`FEATURES_NEEDS_REVIEW`) The previous code state, database
state, and current code state all differ. This occurs most commonly when a user
changes one of her components and then pulls updates to her codebase. Since
there is no way to tell whether the code state or the database state is more
recent/valid, user input is necessary to resolve this state.

- **Rebuildable** (`FEATURES_REBUILDABLE`) This state only applies to
**faux-exportables** and indicates that the database component must and can be
safely updated from the code definition. The database entry does not match the
current code state but does match the previous code state. Features assumes that
in this scenario the user has made no substantive changes and the component can
be updated automatically.

- **Rebuilding** (`FEATURES_REBUILDING`) This state is rarely seen and only
applies to **faux-exportables.** This state is shown when a
`FEATURES_REBUILDABLE` component is *currently* being synced to the database.
Usually this operation is very fast and short lived. However, if the operation
is interrupted (e.g. the server goes down) this state will be seen until the
rebuild locking semaphore is cleared.


How a feature is generated
--------------------------
At a high level Features writes the code in a feature module using the following
steps:

1. An `.info` file describing the components that should be included in a
Feature is generated. It is either read from an existing feature or generated
through the Features UI.

2. Features converts the info file into an `$export` array which contains a list
of elements to be exported. Each component type is given a chance to add to the
export list as well as request that *other* components be given a second chance
to add to the `$export` array.

3. If any additional components have been queued up in the `$pipe` we repeat
step 2 for each of the queued component types.

4. Once a full `$export` array is populated each component renders items from
the `$export` array to PHP code as a exportable defaults hook.

5. Finally, Features writes the code into files and delivers it as a
downloadable package (UI) or writes it directly to a module directory (drush).

This workflow makes a variety of things possible:

### Add components to a feature

Add the components to the `features` array in the feature's `.info` file and run
`drush features-update`. The same operation can be performed using the
*Recreate* page in the Features UI.

### Remove components from a feature

Remove the corresponding component lines from the feature's `.info` file and run
`drush features-update`. The same operation can be performed using the
*Recreate* page in the Features UI.

### Rename a component

Rename a component by changing its name in the feature's `.info` file and the
key and name property of the exported object in the appropriate `.inc` file in
the feature. Note that any references in other configuration objects to the
previous name should also be updated.


Integrating your module with the Features API
---------------------------------------------
This section is for developers interested in adding Features-based management
for the configuration objects in their modules. From the perspective of
Features, there are a few different ways that modules store their configuration:

- In the `variable` table using `variable_set()`. If a module is using variables
for storing configuration, these variable settings can be exported with Features
by using the [Strongarm][1] module.

  **Features integration:** Install the Strongarm module.

- Using a custom table with a serial ID for identifying configuration objects.
If this is the case, you will need to change your schema to use a string
identifier / machine name for each object.

  **Features integration:** Fix your schema first, then see below.

- Using a custom table with a machine name identifier and custom exportables
handling (e.g. you have your own defaults hook handling and export generation).
If this is the case, you will need to implement many of the features hooks
yourself.

  **Features integration:** `hook_features_api()`, `hook_features_export()`,
`hook_features_export_render()`, `hook_features_export_options()`,
`hook_features_revert()`.

- Using a custom table with CTools Export API integration. If this is the case,
Features will automatically have integration with your module. You can implement
any of the Features hooks in order to override the default CTools exportables
integration behavior.

  **Features integration:** Automatically provided. You may implement any of the
Features hooks where you need further customization for your configuration
object.

If it isn't clear by now, we highly recommend using the [CTools][2] Export API
for adding exportables to your module. Stella has written a [fantastic HOWTO][3]
on using the CTools Export API that can get you started.


An overview of Features hooks
-----------------------------
Extensive documentation of the hooks provided by Features is available in
`features.api.php`. This section provides a short overview of each hook and its
role.

- `hook_features_api()` defines one or more component types that are available
to Features for export and a variety of settings for each type.
- `hook_features_export()` processes a list of components, detecting any
dependencies or further components
- `hook_features_export_options()` provides an array of components that can be
exported for a given type.
- `hook_features_export_render()` renders a set of components to code as a
defaults hook.
- `hook_features_revert()` reverts components of a feature back to their default
state.
- `hook_features_rebuild()` updates faux-exportable components back to their
default state. Only applies to faux-exportables.


[1]: http://drupal.org/project/strongarm
[2]: http://drupal.org/project/ctools
[3]: http://civicactions.com/blog/2009/jul/24/using_chaos_tools_module_create_exportables

File

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