Update README.txt for this release.
[project/profiler.git] / README.txt
1
2 Profiler
3 --------
4 Profiler is a library that allows an install profile to be defined as a Drupal
5 `.info` file rather than as a standard PHP script. The benefits of using
6 Profiler for an install profile are:
7
8 - Simpler creation and management of install profiles.
9 - Reduced custom code and complexity in managing installation tasks and
10   configuration.
11 - Inheritance between install profiles and definition of sub-profiles that can
12   override specific aspects of base profiles.
13 - Simplified migration path between Drupal 6.x and 7.x install profiles.
14
15
16 Implementing Profiler in an install profile
17 -------------------------------------------
18 Profiler can be placed in any directory belonging to your install profile. If
19 installed as a standard library the correct location for Profiler is:
20
21     profiles/[yourprofile]/libraries/profiler
22
23 If using a drush make makefile for packaging/distribution, drush make can place
24 Profiler in the standard location with the following lines:
25
26     libraries[profiler][download][type] = "get"
27     libraries[profiler][download][url] = "http://ftp.drupal.org/files/projects/profiler-7.x-2.0-beta1.tar.gz"
28
29 Profiler expects that the `.profile` file initializes the profiler API with the
30 following lines of code:
31
32     <?php
33     !function_exists('profiler_v2') ? require_once('libraries/profiler/profiler.inc') : FALSE;
34     profiler_v2('yourprofile');
35
36 In addition to your profile `.info` file (see below) you may define a
37 `hook_install()` for your install profile allowing you to run any custom code
38 at the very end of the install process. You can add this function to your
39 `.profile` file or a separate `.install` file:
40
41     function yourprofile_install() {
42       // My custom setup code
43     }
44
45 Summary of files:
46
47 - `yourprofile.make`: drush make file including directives for retrieving
48   profiler and unpacking it in the proper location.
49 - `yourprofile.info`: info file containing the core definition of your install
50   profile.
51 - `yourprofile.profile`: contains snippet of code for initializing profiler.
52 - `yourprofile.install`: optional file for defining custom code in 
53   `hook_install()`.
54
55
56 The `.info` file
57 ----------------
58 Each install profile `.info` file is a plain text file that adheres to the
59 Drupal `.info` file syntax. See the included `example.info` for an example of a
60 working install profile `.info` file.
61
62
63 ### Core options
64
65 The following are core options for defining information about your install
66 profile and enabling various components. Options that require additional
67 modules to be included in your install profile are noted below.
68
69 - `name`
70
71   The name of the install profile.
72
73         name = My install profile
74
75 - `description`
76
77   A short description of the install profile.
78
79         description = A custom install profile for video blogging.
80
81 - `core`
82
83   The Drupal core version for which this install profile is intended.
84
85         core = 6.x
86
87 - `base`
88
89   A base install profile from which the current `.info` file should inherit
90   properties.
91
92         base = profile_foo
93
94 - `dependencies`
95
96   An array of Drupal core, contrib, or feature modules to be enabled for this
97   install profile. Need not include the modules defined by
98   `drupal_required_modules()`, ie. block, filter, node, system and user. Any
99   dependencies of the listed modules will also be detected and enabled.
100
101         dependencies[] = book
102         dependencies[] = color
103         dependencies[] = views
104         dependencies[] = myblog
105
106   The following syntax can be used to disable/exclude core modules that would
107   otherwise be inherited from a base install profile:
108
109         dependencies[book] = 0
110
111 - `theme`
112
113   The name of the default theme to be enabled for this install profile
114
115         theme = bluemarine
116
117 - `variables`
118
119   A keyed array of variables and their corresponding values.
120
121         variables[site_frontpage] = admin
122
123 - `users`
124
125   A keyed array of account objects. Each user object is passed nearly directly
126   to user_save(). The following are some common keys you will want to provide:
127
128   - uid: The user id for the account
129   - name: The username for the account
130   - mail: The email address for the account
131   - roles: A comma separated list of roles for this account
132   - status: Status for the account (1 is active, 0 is blocked)
133
134         users[admin][uid] = 1
135         users[admin][name] = admin
136         users[admin][mail] = admin@example.com
137         users[admin][roles] = administrator,manager
138         users[admin][status] = 1
139
140   Note: the user password is assigned a randomly generated string and may not
141   be directly specified in your `.info` file. Even an md5 hashed password
142   exposes a serious vulnerability because of widespread reverse-lookup
143   databases.
144
145 - `nodes`
146
147   A keyed array of node objects. Each node object is passed nearly directly to
148   node_save(). The following are some common keys you will want to provide:
149
150   - type: The node type
151   - title: Title text for the node
152   - body: Body text for the node
153   - uid: The user ID of the node author
154
155         nodes[hello][type] = blog
156         nodes[hello][title] = Hello world!
157         nodes[hello][body] = Lorem ipsum dolor sit amet...
158         nodes[hello][uid] = 1
159
160   - menu: To add the node to a menu
161
162         nodes[hello][menu][link_title] = Hello world!
163         nodes[hello][menu][menu_name] = secondary-links
164
165 - `terms`
166
167   A keyed array of term objects. Each term object is passed nearly directly to
168   taxonomy_term_save(). The following are some common keys you will want to
169   provide:
170
171   - name: The term name
172   - description: Optional. The term description
173   - weight: Optional. An explicit weight for this term
174   - vocabulary_machine_name: The machine name of vocabulary ID to which this
175     term belongs.
176
177         terms[apples][name] = Apples
178         terms[apples][description] = Delicious crunchy fruit.
179         terms[apples][vocabulary_machine_name] = fruit
180
181
182 Maintainer
183 ----------
184 - James Sansbury (q0rban)