README.txt

   1
   2 Current state of Features for Drupal 7
   3 --------------------------------------
   4 Work on Features for D7 is currently aimed at getting to a point where Features
   5 can be used on a new install of Drupal 7 with features that were created on D7.
   6 Once this has been achieved, we will begin working on supporting D6 features as
   7 well as possibly supporting upgrades & migrations between legacy components and
   8 new equivalents (e.g. CCK to fields, imagecache to core image styles).
   9
  10 ### Working components
  11
  12 - ctools
  13 - dependencies
  14 - field
  15 - filter
  16 - image
  17 - menu_custom
  18 - menu_links
  19 - node
  20 - taxonomy
  21 - user_permission
  22 - user_role
  23 - views
  24
  25 ### Has changes to export format between D6 and D7
  26
  27 (@TODO legacy export compatibility)
  28
  29 - filter
  30 - taxonomy
  31
  32 ### Requires upgrade/migration path
  33
  34 - imagecache > image
  35 - content > field
  36
  37
  38 Features 1.x for Drupal 7.x
  39 ---------------------------
  40 The features module enables the capture and management of features in Drupal. A
  41 feature is a collection of Drupal entities which taken together satisfy a
  42 certain use-case.
  43
  44 Features provides a UI and API for taking different site building components
  45 from modules with exportables and bundling them together in a single feature
  46 module. A feature module is like any other Drupal module except that it declares
  47 its components (e.g. views, contexts, CCK fields, etc.) in its `.info` file so
  48 that it can be checked, updated, or reverted programmatically.
  49
  50 Examples of features might be:
  51
  52 - A blog
  53 - A pressroom
  54 - An image gallery
  55 - An e-commerce t-shirt store
  56
  57
  58 Installation
  59 ------------
  60 Features can be installed like any other Drupal module -- place it in the
  61 modules directory for your site and enable it on the `admin/build/modules` page.
  62 To take full advantage of some of the workflow benefits provided by Features,
  63 you should install [Drush][1].
  64
  65
  66 Basic usage
  67 -----------
  68 Features is geared toward usage by developers and site builders. It
  69 is not intended to be used by the general audience of your Drupal site.
  70 Features provides tools for accomplishing two important tasks:
  71
  72 ### Task 1: Export features
  73
  74 You can build features in Drupal by using site building tools that are supported
  75 (see a short list under the *Compatibility* section).
  76
  77 Once you've built and configured functionality on a site, you can export it into
  78 a feature module by using the feature create page at
  79 `admin/structure/features/create`.
  80
  81
  82 ### Task 2: Manage features
  83
  84 The features module also provides a way to manage features through a more
  85 targeted interface than `admin/modules`. The interface at
  86 `admin/structure/features` shows you only feature modules, and will also inform you
  87 if any of their components have been overridden. If this is the case, you can
  88 also re-create features to bring the module code up to date with any changes
  89 that have occurred in the database.
  90
  91
  92 Including custom code and adding to your feature
  93 ------------------------------------------------
  94 Once you've exported your feature you will see that you have several files:
  95
  96     myfeature.info
  97     myfeature.module
  98     myfeature.[*].inc
  99
 100 You can add custom code (e.g. custom hook implementations, other functionality,
 101 etc.) to your feature in `myfeature.module` as you would with any other module.
 102 Do not change or add to any of the features `.inc` files unless you know what
 103 you are doing. These files are written to by features on updates so any custom
 104 changes may be overwritten.
 105
 106
 107 Using Features to manage development
 108 ------------------------------------
 109 Because Features provides a centralized way to manage exportable components and
 110 write them to code it can be used during development in conjunction with a
 111 version control like SVN or git as a way to manage changes between development,
 112 staging and production sites. An example workflow for a developer using Features
 113 is to:
 114
 115 1. Make configuration changes to a feature on her local development site.
 116 2. Update her local feature codebase using `drush features-update`.
 117 3. Commit those changes using `svn commit`.
 118 4. Roll out her changes to the development site codebase by running `svn update`
 119   on the server. Other collaborating developers can also get her changes with
 120   `svn update`.
 121 5. Reverting any configuration on the staging site to match the updated codebase
 122 by running `drush features-revert`.
 123 6. Rinse, repeat.
 124
 125 Features also provides integration with the [Diff][3] module if enabled to show
 126 differences between configuration in the database and that in code. For site
 127 builders interested in using Features for development, enabling the diff module
 128 and reading `API.txt` for more details on the inner workings of Features is
 129 highly recommended.
 130
 131
 132 Drush usage
 133 -----------
 134 (requires Drush v4.5 or higher)
 135
 136 Features provides several useful drush commands:
 137
 138 - `drush features`
 139
 140   List all the available features on your site and their status.
 141
 142 - `drush features-export [feature name] [component list]`
 143
 144   Write a new feature in code containing the components listed.
 145   If called with no arguments, display a list of available components.
 146   If called with one argument, take the argument as a component name and
 147   attempt to create a feature with the same name.
 148
 149   The option '--destination=foo' may be used to specify the path (from Drupal
 150   root) where the feature should be created. The default destination is
 151   'sites/all/modules'.
 152
 153 - `drush features-update [feature name]`
 154
 155   Update the code of an existing feature to include any overrides/changes in
 156   your database (e.g. a new view).
 157
 158 - `drush features-revert [feature name]`
 159
 160   Revert the components of a feature in your site's database to the state
 161   described in your feature module's defaults.
 162
 163 - `drush features-diff [feature name]`
 164
 165   Show a diff between a feature's database components and those in code.
 166   Requires the Diff module.
 167
 168 Additional commands and options can be found using `drush help`.
 169
 170
 171 Compatibility
 172 -------------
 173 Features provides integration for the following exportables:
 174
 175 - CTools export API implementers (Context, Spaces, Boxes, Strongarm, Page
 176   Manager)
 177 - ImageCache
 178 - Views
 179 - [Other contributed modules][2]
 180
 181 Features also provides faux-exportable functionality for the following Drupal
 182 core and contrib components:
 183
 184 - Fields
 185 - Content types
 186 - Input filters
 187 - User roles/permissions
 188 - Custom menus and menu links *
 189 - Taxonomy vocabularies
 190
 191 * Currently in development.
 192
 193
 194 Security Concerns
 195 -----------------
 196 If you are using Features to export Roles and also use those Roles in other
 197 exportable code (like Views filters) you can wind up with an unintended
 198 security hole.  When you import your Feature, if the Roles do not get created
 199 with the exact same Role IDs then your Views filters (or other component) will
 200 be referencing a different Role than you intended.
 201
 202
 203 For developers
 204 --------------
 205 Please read `API.txt` for more information about the concepts and integration
 206 points in the Features module.
 207
 208
 209 Maintainers
 210 -----------
 211 - febbraro (Frank Febbraro)
 212 - hefox (Fox)
 213 - mpotter (Mike Potter)
 214 - timplunkett (Tim Plunkett)
 215
 216
 217 [1]: http://drupal.org/project/drush
 218 [2]: (http://drupal.org/taxonomy/term/11478)