[Summary view] [Print] [Text view]

   1  $Id: README.txt,v 1.1.2.5 2010/07/05 14:28:33 yhahn Exp $
   2  
   3  Features 1.x for Drupal 6.x
   4  ---------------------------
   5  The features module enables the capture and management of features in Drupal. A
   6  feature is a collection of Drupal entities which taken together satisfy a
   7  certain use-case.
   8  
   9  Features provides a UI and API for taking different site building components
  10  from modules with exportables and bundling them together in a single feature
  11  module. A feature module is like any other Drupal module except that it declares
  12  its components (e.g. views, contexts, CCK fields, etc.) in its `.info` file so
  13  that it can be checked, updated, or reverted programmatically.
  14  
  15  Examples of features might be:
  16  
  17  - A blog
  18  - A pressroom
  19  - An image gallery
  20  - An e-commerce t-shirt store
  21  
  22  
  23  Installation
  24  ------------
  25  Features can be installed like any other Drupal module -- place it in the
  26  modules directory for your site and enable it on the `admin/build/modules` page.
  27  To take full advantage of some of the workflow benefits provided by Features,
  28  you should install [Drush][1].
  29  
  30  
  31  Basic usage
  32  -----------
  33  Features is geared toward usage by developers and site builders. It
  34  is not intended to be used by the general audience of your Drupal site.
  35  Features provides tools for accomplishing two important tasks:
  36  
  37  ### Task 1: Export features
  38  
  39  You can build features in Drupal by using site building tools that are supported
  40  (see a short list under the *Compatibility* section).
  41  
  42  Once you've built and configured functionality on a site, you can export it into
  43  a feature module by using the feature create page at
  44  `admin/build/features/create`.
  45  
  46  
  47  ### Task 2: Manage features
  48  
  49  The features module also provides a way to manage features through a more
  50  targeted interface than `admin/build/modules`. The interface at
  51  `admin/build/features` shows you only feature modules, and will also inform you
  52  if any of their components have been overridden. If this is the case, you can
  53  also re-create features to bring the module code up to date with any changes
  54  that have occurred in the database.
  55  
  56  
  57  Including custom code and adding to your feature
  58  ------------------------------------------------
  59  Once you've exported your feature you will see that you have several files:
  60  
  61      myfeature.info
  62      myfeature.module
  63      myfeature.[*].inc
  64  
  65  You can add custom code (e.g. custom hook implementations, other functionality,
  66  etc.) to your feature in `myfeature.module` as you would with any other module.
  67  Do not change or add to any of the features `.inc` files unless you know what
  68  you are doing. These files are written to by features on updates so any custom
  69  changes may be overwritten.
  70  
  71  
  72  Using Features to manage development
  73  ------------------------------------
  74  Because Features provides a centralized way to manage exportable components and
  75  write them to code it can be used during development in conjunction with a
  76  version control like SVN or git as a way to manage changes between development,
  77  staging and production sites. An example workflow for a developer using Features
  78  is to:
  79  
  80  1. Make configuration changes to a feature on her local development site.
  81  2. Update her local feature codebase using `drush features-update`.
  82  3. Commit those changes using `svn commit`.
  83  4. Roll out her changes to the development site codebase by running `svn update`
  84    on the server. Other collaborating developers can also get her changes with
  85    `svn update`.
  86  5. Reverting any configuration on the staging site to match the updated codebase
  87  by running `drush features-revert`.
  88  6. Rinse, repeat.
  89  
  90  Features also provides integration with the [Diff][3] module if enabled to show
  91  differences between configuration in the database and that in code. For site
  92  builders interested in using Features for development, enabling the diff module
  93  and reading `API.txt` for more details on the inner workings of Features is
  94  highly recommended.
  95  
  96  
  97  Drush usage
  98  -----------
  99  Features provides several useful drush commands:
 100  
 101  - `drush features`
 102  
 103    List all the available features on your site and their status.
 104  
 105  - `drush features-export [feature name] [component list]`
 106  
 107    Write a new feature in code containing the components listed.
 108  
 109  - `drush features-update [feature name]`
 110  
 111    Update the code of an existing feature to include any overrides/changes in
 112    your database (e.g. a new view).
 113  
 114  - `drush features-revert [feature name]`
 115  
 116    Revert the components of a feature in your site's database to the state
 117    described in your feature module's defaults.
 118  
 119  - `drush features-diff [feature name]`
 120  
 121    Show a diff between a feature's database components and those in code.
 122    Requires the Diff module.
 123  
 124  Additional commands and options can be found using `drush help`.
 125  
 126  
 127  Compatibility
 128  -------------
 129  Features provides integration for the following exportables:
 130  
 131  - CTools export API implementers (Context, Spaces, Boxes, Strongarm, Page
 132    Manager)
 133  - ImageCache
 134  - Views
 135  - [Other contributed modules][2]
 136  
 137  Features also provides faux-exportable functionality for the following Drupal
 138  core and contrib components:
 139  
 140  - CCK fields
 141  - CCK fieldgroups
 142  - Content types
 143  - Input filters
 144  - User roles/permissions
 145  - Custom menus and menu links *
 146  - Taxonomy vocabularies *
 147  
 148  * Currently in development.
 149  
 150  
 151  For developers
 152  --------------
 153  Please read `API.txt` for more information about the concepts and integration
 154  points in the Features module.
 155  
 156  
 157  Maintainers
 158  -----------
 159  - yhahn (Young Hahn)
 160  - jmiccolis (Jeff Miccolis)
 161  
 162  
 163  [1]: http://drupal.org/project/drush
 164  [2]: (http://drupal.org/taxonomy/term/11478)