Roll 1.x branch back before 1.1UI was merged
[project/features.git] / 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)