example.profile

You are here

  1. 7 developer/example.profile
  2. 6 developer/example.profile
  3. 8 developer/example.profile

Functions

Namesort descending Description
example_form Form API array definition for the example form.
example_form_alter Implementation of hook_form_alter().
example_form_submit Form API submit for the example form.
example_profile_details Return a description of the profile for the initial installation screen.
example_profile_modules Return an array of the modules to be enabled when this profile is installed.
example_profile_tasks Perform any final installation tasks for this profile.
example_profile_task_list Return a list of tasks that this profile supports.

File

developer/example.profile
View source
  1. <?php
  2. /**
  3. * Return an array of the modules to be enabled when this profile is installed.
  4. *
  5. * @return
  6. * An array of modules to enable.
  7. */
  8. function example_profile_modules() {
  9. // This example profile enables the same optional modules as default.profile,
  10. // plus the 'locale' module. But however, any available modules may be added
  11. // to the list, including contributed modules, which will be then reqired by
  12. // the installer. Configuration of these modules may be handled later by tasks.
  13. return array('color', 'comment', 'help', 'menu', 'taxonomy', 'dblog', 'locale');
  14. }
  15. /**
  16. * Return a description of the profile for the initial installation screen.
  17. *
  18. * @return
  19. * An array with keys 'name' and 'description' describing this profile,
  20. * and optional 'language' to override the language selection for
  21. * language-specific profiles.
  22. */
  23. function example_profile_details() {
  24. return array(
  25. // These two strings will be displayed on the initial profile-selecion
  26. // page, as a radio-button label, and description below. Because the
  27. // page is shown before language selection, there's no point to attempt
  28. // translation in any way; it's always shown in English. But however,
  29. // if the profile is focused to install Drupal in some other language,
  30. // these strings may be provided in that language, assuming that the
  31. // maintainer of the installed new Drupal site understands that better.
  32. // To skip the untranslatable profile-selection page entirely, ensure
  33. // that there's just one profile available, by deleting the default
  34. // profile.
  35. 'name' => 'Example installation profile',
  36. 'description' => 'This is an example installation profile for Drupal 6.x, demonstrating some of the principles to developers.',
  37. // This example profile is supposed to be language-focused, so we
  38. // inject the language selection here, hiding the language selection
  39. // screen from the user, and so saving one unnecessary, untranslatable
  40. // step. Any profile focused to features rather than language, or
  41. // expecting more languages to choose from, should omit the line below.
  42. // We're using Czech as an example here; it only works if a valid file
  43. // cs.po (with installer translations) is provided in the
  44. // profiles/example/translations directory, otherwise default English
  45. // will be used instead.
  46. 'language' => 'cs',
  47. );
  48. }
  49. /**
  50. * Return a list of tasks that this profile supports.
  51. *
  52. * @return
  53. * A keyed array of tasks the profile will perform during
  54. * the final stage. The keys of the array will be used internally,
  55. * while the values will be displayed to the user in the installer
  56. * task list.
  57. */
  58. function example_profile_task_list() {
  59. return array(
  60. // Here we define names of the custom tasks we're about to perform,
  61. // so that these will be shown in the tasks list on the
  62. // installer UI. The keys may be anything (internal use only),
  63. // excepting the reserved tasks (as listed in install_reserved_tasks()
  64. // inside install.php). The strings may be translated with the st()
  65. // wrapper (translations provided in the install profile's .po file),
  66. // but sometimes there's no point in doing that, if the profile is
  67. // only focused to a single language. We only need to list tasks,
  68. // for which a page will be displayed; internally, unlisted keys
  69. // may be well used too. It's also possible to return dynamic data
  70. // here, adding/removing tasks on-the-fly depending on previous
  71. // steps.
  72. 'task1' => st('Example question'),
  73. 'task2' => st('Example summary'),
  74. );
  75. }
  76. /**
  77. * Perform any final installation tasks for this profile.
  78. *
  79. * The installer goes through the profile-select -> locale-select
  80. * -> requirements -> database -> locale-initial-batch -> configure
  81. * -> locale-remaining-batch -> finished -> done tasks in this order,
  82. * if you don't implement this function in your profile.
  83. *
  84. * If this function is implemented, you can have any number of
  85. * custom tasks to perform after 'configure', implementing a state
  86. * machine here to walk the user through those tasks. First time,
  87. * this function gets called with $task set to 'profile', and you
  88. * can advance to further tasks by setting $task to your tasks'
  89. * identifiers, used as array keys in the hook_profile_task_list()
  90. * above. You must avoid the reserved tasks listed in
  91. * install_reserved_tasks(). If you implement your custom tasks,
  92. * this function will get called in every HTTP request (for form
  93. * processing, printing your information screens and so on) until
  94. * you advance to the 'profile-finished' task, with which you
  95. * hand control back to the installer. Each custom page you
  96. * return needs to provide a way to continue, such as a form
  97. * submission or a link. You should also set custom page titles.
  98. *
  99. * You should define the list of custom tasks you implement by
  100. * returning an array of them in hook_profile_task_list(), as these
  101. * show up in the list of tasks on the installer user interface.
  102. *
  103. * Remember that the user will be able to reload the pages multiple
  104. * times, so you might want to use variable_set() and variable_get()
  105. * to remember your data and control further processing, if $task
  106. * is insufficient. Should a profile want to display a form here,
  107. * it can; the form should set '#redirect' to FALSE, and rely on
  108. * an action in the submit handler, such as variable_set(), to
  109. * detect submission and proceed to further tasks. See the configuration
  110. * form handling code in install_tasks() for an example.
  111. *
  112. * Important: Any temporary variables should be removed using
  113. * variable_del() before advancing to the 'profile-finished' phase.
  114. *
  115. * @param $task
  116. * The current $task of the install system. When hook_profile_tasks()
  117. * is first called, this is 'profile'.
  118. * @param $url
  119. * Complete URL to be used for a link or form action on a custom page,
  120. * if providing any, to allow the user to proceed with the installation.
  121. *
  122. * @return
  123. * An optional HTML string to display to the user. Only used if you
  124. * modify the $task, otherwise discarded.
  125. */
  126. function example_profile_tasks(&$task, $url) {
  127. // First time, this function will be called with the 'profile' task.
  128. // In this case, we advance the pointer to our first custom task, to
  129. // indicate that this profile needs more runs to complete, and we
  130. // also perform some initial settings.
  131. if ($task == 'profile') {
  132. $task = 'task1';
  133. // The following part is a verbatim from default.profile, doing some
  134. // basic settings, that may be easily customized here. For a simple
  135. // profile, with no need for custom UI screens, this will be the
  136. // only code inside hook_profile_tasks(); in that case there's
  137. // no need to modify $task, as demonstrated in default.profile:
  138. // If $task is not changed, this function gets only called once.
  139. // Insert default user-defined node types into the database. For a complete
  140. // list of available node type attributes, refer to the node type API
  141. // documentation at: http://api.drupal.org/api/HEAD/function/hook_node_info.
  142. $types = array(
  143. array(
  144. 'type' => 'page',
  145. 'name' => st('Page'),
  146. 'module' => 'node',
  147. 'description' => st("A <em>page</em>, similar in form to a <em>story</em>, is a simple method for creating and displaying information that rarely changes, such as an \"About us\" section of a website. By default, a <em>page</em> entry does not allow visitor comments and is not featured on the site's initial home page."),
  148. 'custom' => TRUE,
  149. 'modified' => TRUE,
  150. 'locked' => FALSE,
  151. 'help' => '',
  152. 'min_word_count' => '',
  153. ),
  154. array(
  155. 'type' => 'story',
  156. 'name' => st('Story'),
  157. 'module' => 'node',
  158. 'description' => st("A <em>story</em>, similar in form to a <em>page</em>, is ideal for creating and displaying content that informs or engages website visitors. Press releases, site announcements, and informal blog-like entries may all be created with a <em>story</em> entry. By default, a <em>story</em> entry is automatically featured on the site's initial home page, and provides the ability to post comments."),
  159. 'custom' => TRUE,
  160. 'modified' => TRUE,
  161. 'locked' => FALSE,
  162. 'help' => '',
  163. 'min_word_count' => '',
  164. ),
  165. );
  166. foreach ($types as $type) {
  167. $type = (object) _node_type_set_defaults($type);
  168. node_type_save($type);
  169. }
  170. // Default page to not be promoted and have comments disabled.
  171. variable_set('node_options_page', array('status'));
  172. variable_set('comment_page', COMMENT_NODE_DISABLED);
  173. // Don't display date and author information for page nodes by default.
  174. $theme_settings = variable_get('theme_settings', array());
  175. $theme_settings['toggle_node_info_page'] = FALSE;
  176. variable_set('theme_settings', $theme_settings);
  177. // Update the menu router information.
  178. menu_rebuild();
  179. }
  180. // (End of verbatim from default.profile)
  181. // Our custom tasks now follow. Just like install.php, we use a construct
  182. // of if() statements here, to allow passing from one task to another in
  183. // the same request, after the $task pointer got modified, and ensure
  184. // that correct code gets executed on page reloads.
  185. // Our first custom task displays a form.
  186. if ($task == 'task1') {
  187. // FAPI takes care of most of the operations, as page reloads go.
  188. // We pass the $url to the form definition, to be used for form action.
  189. $output = drupal_get_form('example_form', $url);
  190. // The forms inside installer profiles may not use redirection, because
  191. // that will break the installer workflow. So we need an other way to
  192. // detect whether the form was successfully submitted, meaning that
  193. // the submit handler already performed it's job. This depends on the
  194. // exact use case; in this example profile, we check whether some
  195. // user-submitted text was already stored into our variable.
  196. if (!variable_get('example_submitted_text', FALSE)) {
  197. // The variable is still empty, meaning that the drupal_get_form()
  198. // call above haven't finished the form yet. We set a page-title
  199. // here, and return the rendered form to the installer, to be
  200. // shown to the user. Since $task is still set to 'task1', this
  201. // code will be re-run on next page request, proceeding further
  202. // if possible.
  203. drupal_set_title(st('Example question'));
  204. return $output;
  205. }
  206. else {
  207. // The form was submitted, so now we advance to the next task.
  208. $task = 'task2';
  209. }
  210. }
  211. // Our second custom task shows a simple page, summarizing the previous
  212. // step.
  213. if ($task == 'task2') {
  214. // To display a simple HTML page through the installer, we just set
  215. // title, and return the content. But since this code is now run on
  216. // every page request (until we change the $task), we need to detect
  217. // whether the user already decided to finish this task by clicking
  218. // to the provided link (as opposed to showing the page first time,
  219. // or a reload). This is done through an extra GET string added to
  220. // the link.
  221. if (empty($_GET['example_finished'])) {
  222. // The GET string is not present, meaning that this page request
  223. // is not coming from the link being clicked, and so we need to
  224. // render the page.
  225. $output = '<p>'. st('This page is a demonstration of custom page shown by a custom task of installer profile.') .'</p>';
  226. $output .= '<p>'. st('On the previous page, the following text was entered: %text.', array('%text' => variable_get('example_submitted_text', ''))) .'</p>';
  227. // We build the link from $url provided by the installer, adding
  228. // the extra GET string mentioned above.
  229. $output .= '<p><a href="'. $url .'&example_finished=yes">'. st('Click here to continue') .'</a></p>';
  230. drupal_set_title(st('Example summary'));
  231. return $output;
  232. }
  233. else {
  234. // The GET string is present, meaning that the user already
  235. // reviewed the page and clicked the link. We can advance to
  236. // further tasks now, but since we haven't any left, we just
  237. // finish our business here:
  238. // The variable 'example_submitted_text' was just a temporary
  239. // storage for our testing. Variables may be used for such
  240. // purposes here, but we should remove them before passing
  241. // control back to installer, to avoid leaving useless temporary
  242. // data in the variables table of the newly installed Drupal
  243. // site.
  244. variable_del('example_submitted_text');
  245. // By advancing to the 'profile-finished' task, we hand control
  246. // back to the installer, when we are done.
  247. $task = 'profile-finished';
  248. }
  249. }
  250. }
  251. /**
  252. * Form API array definition for the example form.
  253. */
  254. function example_form(&$form_state, $url) {
  255. // This is just a very simple form with one textfield, and a
  256. // submit button.
  257. $form['example_text'] = array(
  258. '#type' => 'textfield',
  259. '#title' => st('Testing text'),
  260. '#default_value' => '',
  261. '#size' => 45,
  262. '#maxlength' => 45,
  263. '#required' => TRUE,
  264. '#description' => st('This is an example form demonstrating forms usage in the installer profiles tasks. Enter any text to see what happens.'),
  265. );
  266. $form['continue'] = array(
  267. '#type' => 'submit',
  268. '#value' => st('Continue'),
  269. );
  270. // Note that #action is set to the url passed through from
  271. // installer, ensuring that it points to the same page, and
  272. // #redirect is FALSE to avoid broken installer workflow.
  273. $form['errors'] = array();
  274. $form['#action'] = $url;
  275. $form['#redirect'] = FALSE;
  276. return $form;
  277. }
  278. /**
  279. * Form API submit for the example form.
  280. */
  281. function example_form_submit($form, &$form_state) {
  282. // This code is executed, while the form is submitted. There's
  283. // a wide range of possible operations to execute here, such as
  284. // process and store settings, enable extra modules, or save
  285. // contents to the new site (unless the operations are too
  286. // expensive: the Batch API is a good choice for such operations,
  287. // but it needs to be coded inside hook_profile_tasks(), not
  288. // here).
  289. // In this example profile, we just store the submitted text to
  290. // a temporary variable, to be used in further tasks.
  291. variable_set('example_submitted_text', $form_state['values']['example_text']);
  292. }
  293. /**
  294. * Implementation of hook_form_alter().
  295. *
  296. * Allows the profile to alter the site-configuration form. This is
  297. * called through custom invocation, so $form_state is not populated.
  298. */
  299. function example_form_alter(&$form, $form_state, $form_id) {
  300. if ($form_id == 'install_configure') {
  301. // Here we can play with the site configuration form provided
  302. // by the installer, by changing the prepopulated $form array.
  303. // See install_configure_form() inside install.php for its
  304. // default content.
  305. // Set default for site name field.
  306. $form['site_information']['site_name']['#default_value'] = 'Drupal example';
  307. // Set default for administrator account name.
  308. $form['admin_account']['account']['name']['#default_value'] = 'admin';
  309. // Remove the timezone setting, as this profile is supposed to be
  310. // focused on Czech language as an example, where the timezone is
  311. // obvious.
  312. unset($form['server_settings']['date_default_timezone']);
  313. // Define the timezone as fixed value instead, so that the submit
  314. // handler of the site configuration form may still process it.
  315. $form['date_default_timezone'] = array(
  316. '#type' => 'value',
  317. '#value' => '3600',
  318. );
  319. }
  320. }