diff --git a/checklistapi.api.php b/checklistapi.api.php index 9f280e4475619340380155eb6cc04c3355fbaaee..c9f155d29a6b4ef2a30b85da7eceed4d18a0845b 100644 --- a/checklistapi.api.php +++ b/checklistapi.api.php @@ -14,59 +14,64 @@ * Define all checklists provided by the module. * * Any number of checklists can be defined in an implementation of this hook. - * Checklist API will register a menu item and create a permission for each one. + * Checklist API will register menu items and create permissions for each one. * * @return array * An array of checklists. Each checklist is keyed by an arbitrary unique * identifier. The corresponding multidimensional array describing the * checklist may contain the following key-value pairs: - * - #title: Required. The title of the checklist. - * - #description: A brief description of the checklist for its corresponding - * menu item. - * - #path: Required. The Drupal path where the checklist will be accessed. - * - #help: User help to be displayed in the "System help" block via - * hook_help(). - * - #menu_name: Set this to a custom menu if you don't want your item to be - * placed in Navigation. - * - #weight: An integer used to sort the list of checklists before being - * output; lower numbers appear before higher numbers. - * - Any number of arrays representing groups of items, presented as vertical - * tabs. Each group is keyed by an arbitrary unique identifier. The - * corresponding multimensional array describing the group may contain the - * following key-value pairs: - * - #title: Required. The title of the group used as the vertical tab - * label. - * - #description: A description of the group. - * - #weight: An integer used to sort the list of groups before being - * output; lower numbers appear before higher numbers. + * - #title: The title of the checklist. + * - #path: The Drupal path where the checklist will be accessed. + * - #description: (optional) A brief description of the checklist for its + * corresponding menu item. + * - #help: (optional) User help to be displayed in the "System help" block + * via hook_help(). + * - #menu_name: (optional) Set this to a custom menu if you don't want your + * item to be placed in Navigation. + * - #weight: (optional) A floating point number used to sort the list of + * checklists before being output. Lower numbers appear before higher + * numbers. + * - Any number of arrays representing groups of items, to be presented as + * vertical tabs. Each group is keyed by an arbitrary identifier, unique in + * the scope of the checklist. The corresponding multimensional array + * describing the group may contain the following key-value pairs: + * - #title: The title of the group, used as the vertical tab label. + * - #description: (optional) A description of the group. + * - #weight: (optional) A floating point number used to sort the list of + * groups before being output. Lower numbers appear before higher numbers. * - Any number of arrays representing checklist items. Each item is keyed - * by an arbitrary unique identifier. The corresponding multimensional - * array describing the item may contain the following key-value pairs: - * - #title: Required. The title of the item. - * - #description: A description of the item. - * - #default_value: The default checked state of the item--TRUE for - * checked or FALSE for unchecked. Defaults to FALSE. This is useful for - * automatically checking off tasks that can be programmatically tested - * (e.g. a module is installed or a setting set). - * - #weight: An integer used to sort the list of items before being - * output; lower numbers appear before higher numbers. + * by an arbitrary identifier, unique in the scope of the checklist. The + * corresponding multimensional array describing the item may contain the + * following key-value pairs: + * - #title: The title of the item. + * - #description: (optional) A description of the item, for display + * beneath the title. + * - #default_value: (optional) The default checked state of the + * item--TRUE for checked or FALSE for unchecked. Defaults to FALSE. + * This is useful for automatically checking items that can be + * programmatically tested (e.g. a module is installed or a variable has + * a certain value). + * - #weight: (optional) A floating point number used to sort the list of + * items before being output. Lower numbers appear before higher + * numbers. * - Any number of arrays representing links. Each link is keyed by an * arbitrary unique identifier. The corresponding multimensional array * describing the link may contain the following key-value pairs: * - #text: The link text. * - #path: The link path. - * - #context: The context in which the link may appear. May be one of - * the following: - * - CHECKLISTAPI_LINK_CONTEXT_ANY: Default. The link will always + * - #options: (optional) An associative array of additional options + * used by the l() function. + * - #context: (optional) The context in which the link may appear. May + * be one of the following: + * - CHECKLISTAPI_LINK_CONTEXT_ANY: (default) The link will always * appear. * - CHECKLISTAPI_LINK_CONTEXT_ITEM_CHECKED: The link will appear if - * the item it belongs to has been checked off. + * the item it belongs to has been previously checked. * - CHECKLISTAPI_LINK_CONTEXT_ITEM_UNCHECKED: The link will appear if - * the item it belongs to has not checked off. - * - #options: An associative array of additional options used by the - * l() function. - * - #weight: An integer used to sort the list of items before being - * output; lower numbers appear before higher numbers. + * the item it belongs to has not been previously checked. + * - #weight: (optional) A floating point number used to sort the list + * of items before being output. Lower numbers appear before higher + * numbers. * * For a working example, see checklistapi_example.module. * @@ -75,21 +80,24 @@ */ function hook_checklistapi_checklist_info() { $checklists = array(); - $checklists['example'] = array( + $checklists['example_checklist'] = array( '#title' => t('Example checklist'), - '#description' => t('An example checklist.'), '#path' => 'example-checklist', + '#description' => t('An example checklist.'), '#help' => t('<p>This is an example checklist.</p>'), 'example_group' => array( '#title' => t('Example group'), '#description' => t('<p>Here are some example items.</p>'), - 'example_item' => array( - '#title' => t('Example item'), + 'example_item_1' => array( + '#title' => t('Example item 1'), 'example_link' => array( '#text' => t('Example.com'), '#path' => 'http://www.example.com/', ), ), + 'example_item_2' => array( + '#title' => t('Example item 2'), + ), ), ); return $checklists; @@ -99,13 +107,11 @@ function hook_checklistapi_checklist_info() { * Alter checklist definitions. * * This hook is invoked by checklistapi_get_checklist_info(). The checklist - * definitions are passed in by reference. Each element of the $checklists array - * is one returned by a module from checklistapi_get_checklist_info(). - * Additional checklists may be added, or existing checklists may be altered or - * removed. + * definitions are passed in by reference. Additional checklists may be added, + * or existing checklists may be altered or removed. * - * @param array $checklists - * A multidimensional array of checklists definitions returned from + * @param array $definitions + * The multidimensional array of checklist definitions returned by * hook_checklistapi_checklist_info(). * * For a working example, see checklistapi_example.module. @@ -113,13 +119,20 @@ function hook_checklistapi_checklist_info() { * @see checklistapi_get_checklist_info() * @see hook_checklistapi_checklist_info() */ -function hook_checklistapi_checklist_info_alter(array &$checklists) { +function hook_checklistapi_checklist_info_alter(array &$definitions) { // Add an item. - $checklists['example']['example_group']['sample_item'] = array( - 'title' => t('Sample item'), + $definitions['example_checklist']['example_group']['new_item'] = array( + 'title' => t('New item'), + ); + // Add a group. + $definitions['example_checklist']['new_group'] = array( + '#title' => t('New group'), ); + // Move an item. + $definitions['example_checklist']['new_group']['example_item_1'] = $definitions['example_checklist']['example_group']['example_item_1']; + unset($definitions['example_checklist']['example_group']['example_item_1']); // Remove an item. - unset($checklists['example']['example_group']['example_item']); + unset($definitions['example_checklist']['example_group']['example_item_2']); } /** diff --git a/checklistapi.module b/checklistapi.module index 9419d516ea1503f60b5221454dc891cc59323de2..4b8d0c9a21995c5c9e72d698884c2dbb2f1f50d2 100644 --- a/checklistapi.module +++ b/checklistapi.module @@ -14,12 +14,14 @@ define('CHECKLISTAPI_LINK_CONTEXT_ANY', 1); /** - * Link should only be shown if the item it belongs to has been checked off. + * Link should only be shown if the item it belongs to has been previously + * checked. */ define('CHECKLISTAPI_LINK_CONTEXT_ITEM_CHECKED', 2); /** - * Link should only be shown if the item it belongs to has not been checked off. + * Link should only be shown if the item it belongs to has not been previously + * checked. */ define('CHECKLISTAPI_LINK_CONTEXT_ITEM_UNCHECKED', 3); diff --git a/checklistapi_example/checklistapi_example.module b/checklistapi_example/checklistapi_example.module index 18d3550a9ecf326f068bf9ef7ff72c7db2c9a70f..68be918a34e4a462d2960d6caa4acaf10cdfb1f1 100644 --- a/checklistapi_example/checklistapi_example.module +++ b/checklistapi_example/checklistapi_example.module @@ -16,8 +16,8 @@ function checklistapi_example_checklistapi_checklist_info() { $checklists = array(); $checklists['example_checklist'] = array( '#title' => t('Checklist API example'), - '#description' => t('An example implementation of the Checklist API.'), '#path' => 'admin/config/development/checklistapi-example', + '#description' => t('An example implementation of the Checklist API.'), '#help' => t('<p>This checklist based on <a href="http://buytaert.net/drupal-learning-curve">Dries Buytaert\'s Drupal learning curve</a> is an example implementation of the <a href="http://drupal.org/project/checklistapi">Checklist API</a>.</p>'), 'i_suck' => array( '#title' => t('I suck'), diff --git a/lib/Drupal/checklistapi/ChecklistapiChecklist.php b/lib/Drupal/checklistapi/ChecklistapiChecklist.php index e46dc89df13765ac0c28df4a8588a007ea7d11f3..49df48d15a04cda513594a2bb61ec45d8cd32290 100644 --- a/lib/Drupal/checklistapi/ChecklistapiChecklist.php +++ b/lib/Drupal/checklistapi/ChecklistapiChecklist.php @@ -92,8 +92,8 @@ class ChecklistapiChecklist { $this->items[$group_key] = $definition[$group_key]; unset($definition[$group_key]); } - foreach ($definition as $key => $value) { - $property_name = checklistapi_strtolowercamel(drupal_substr($key, 1)); + foreach ($definition as $property_key => $value) { + $property_name = checklistapi_strtolowercamel(drupal_substr($property_key, 1)); $this->$property_name = $value; } $this->savedProgress = variable_get($this->getSavedProgressVariableName(), array()); @@ -135,7 +135,9 @@ class ChecklistapiChecklist { * Saves checklist progress to a Drupal variable. * * @param array $values - * A multidimensional array representing. + * A multidimensional array of form state checklist values. + * + * @see checklistapi_checklist_form_submit() */ public function saveProgress(array $values) { global $user; diff --git a/tests/modules/checklistapi_test/checklistapi_test.module b/tests/modules/checklistapi_test/checklistapi_test.module index 8db3517e7ca288a7e9e4519d6b1d77edc01340bb..18a16704b5e2e595f3d075e52e2f6efdd3ef6335 100644 --- a/tests/modules/checklistapi_test/checklistapi_test.module +++ b/tests/modules/checklistapi_test/checklistapi_test.module @@ -12,8 +12,8 @@ function checklistapi_test_checklistapi_checklist_info() { $checklists = array(); $checklists['test_checklist'] = array( '#title' => t('Checklist API test'), - '#description' => t('A test checklist.'), '#path' => 'admin/config/development/checklistapi-test', + '#description' => t('A test checklist.'), '#help' => t('<p>This is a test checklist.</p>'), 'group_two' => array( '#title' => t('Group two'),