Commit ce4f94d8 authored by TravisCarden's avatar TravisCarden

By TravisCarden: Expanded and improved API documentation.

parent 1b8dbfff
...@@ -14,59 +14,64 @@ ...@@ -14,59 +14,64 @@
* Define all checklists provided by the module. * Define all checklists provided by the module.
* *
* Any number of checklists can be defined in an implementation of this hook. * 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 * @return array
* An array of checklists. Each checklist is keyed by an arbitrary unique * An array of checklists. Each checklist is keyed by an arbitrary unique
* identifier. The corresponding multidimensional array describing the * identifier. The corresponding multidimensional array describing the
* checklist may contain the following key-value pairs: * checklist may contain the following key-value pairs:
* - #title: Required. The title of the checklist. * - #title: The title of the checklist.
* - #description: A brief description of the checklist for its corresponding * - #path: The Drupal path where the checklist will be accessed.
* menu item. * - #description: (optional) A brief description of the checklist for its
* - #path: Required. The Drupal path where the checklist will be accessed. * corresponding menu item.
* - #help: User help to be displayed in the "System help" block via * - #help: (optional) User help to be displayed in the "System help" block
* hook_help(). * via hook_help().
* - #menu_name: Set this to a custom menu if you don't want your item to be * - #menu_name: (optional) Set this to a custom menu if you don't want your
* placed in Navigation. * item to be placed in Navigation.
* - #weight: An integer used to sort the list of checklists before being * - #weight: (optional) A floating point number used to sort the list of
* output; lower numbers appear before higher numbers. * checklists before being output. Lower numbers appear before higher
* - Any number of arrays representing groups of items, presented as vertical * numbers.
* tabs. Each group is keyed by an arbitrary unique identifier. The * - Any number of arrays representing groups of items, to be presented as
* corresponding multimensional array describing the group may contain the * vertical tabs. Each group is keyed by an arbitrary identifier, unique in
* following key-value pairs: * the scope of the checklist. The corresponding multimensional array
* - #title: Required. The title of the group used as the vertical tab * describing the group may contain the following key-value pairs:
* label. * - #title: The title of the group, used as the vertical tab label.
* - #description: A description of the group. * - #description: (optional) A description of the group.
* - #weight: An integer used to sort the list of groups before being * - #weight: (optional) A floating point number used to sort the list of
* output; lower numbers appear before higher numbers. * groups before being output. Lower numbers appear before higher numbers.
* - Any number of arrays representing checklist items. Each item is keyed * - Any number of arrays representing checklist items. Each item is keyed
* by an arbitrary unique identifier. The corresponding multimensional * by an arbitrary identifier, unique in the scope of the checklist. The
* array describing the item may contain the following key-value pairs: * corresponding multimensional array describing the item may contain the
* - #title: Required. The title of the item. * following key-value pairs:
* - #description: A description of the item. * - #title: The title of the item.
* - #default_value: The default checked state of the item--TRUE for * - #description: (optional) A description of the item, for display
* checked or FALSE for unchecked. Defaults to FALSE. This is useful for * beneath the title.
* automatically checking off tasks that can be programmatically tested * - #default_value: (optional) The default checked state of the
* (e.g. a module is installed or a setting set). * item--TRUE for checked or FALSE for unchecked. Defaults to FALSE.
* - #weight: An integer used to sort the list of items before being * This is useful for automatically checking items that can be
* output; lower numbers appear before higher numbers. * 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 * - Any number of arrays representing links. Each link is keyed by an
* arbitrary unique identifier. The corresponding multimensional array * arbitrary unique identifier. The corresponding multimensional array
* describing the link may contain the following key-value pairs: * describing the link may contain the following key-value pairs:
* - #text: The link text. * - #text: The link text.
* - #path: The link path. * - #path: The link path.
* - #context: The context in which the link may appear. May be one of * - #options: (optional) An associative array of additional options
* the following: * used by the l() function.
* - CHECKLISTAPI_LINK_CONTEXT_ANY: Default. The link will always * - #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. * appear.
* - CHECKLISTAPI_LINK_CONTEXT_ITEM_CHECKED: The link will appear if * - 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 * - CHECKLISTAPI_LINK_CONTEXT_ITEM_UNCHECKED: The link will appear if
* the item it belongs to has not checked off. * the item it belongs to has not been previously checked.
* - #options: An associative array of additional options used by the * - #weight: (optional) A floating point number used to sort the list
* l() function. * of items before being output. Lower numbers appear before higher
* - #weight: An integer used to sort the list of items before being * numbers.
* output; lower numbers appear before higher numbers.
* *
* For a working example, see checklistapi_example.module. * For a working example, see checklistapi_example.module.
* *
...@@ -75,21 +80,24 @@ ...@@ -75,21 +80,24 @@
*/ */
function hook_checklistapi_checklist_info() { function hook_checklistapi_checklist_info() {
$checklists = array(); $checklists = array();
$checklists['example'] = array( $checklists['example_checklist'] = array(
'#title' => t('Example checklist'), '#title' => t('Example checklist'),
'#description' => t('An example checklist.'),
'#path' => 'example-checklist', '#path' => 'example-checklist',
'#description' => t('An example checklist.'),
'#help' => t('<p>This is an example checklist.</p>'), '#help' => t('<p>This is an example checklist.</p>'),
'example_group' => array( 'example_group' => array(
'#title' => t('Example group'), '#title' => t('Example group'),
'#description' => t('<p>Here are some example items.</p>'), '#description' => t('<p>Here are some example items.</p>'),
'example_item' => array( 'example_item_1' => array(
'#title' => t('Example item'), '#title' => t('Example item 1'),
'example_link' => array( 'example_link' => array(
'#text' => t('Example.com'), '#text' => t('Example.com'),
'#path' => 'http://www.example.com/', '#path' => 'http://www.example.com/',
), ),
), ),
'example_item_2' => array(
'#title' => t('Example item 2'),
),
), ),
); );
return $checklists; return $checklists;
...@@ -99,13 +107,11 @@ function hook_checklistapi_checklist_info() { ...@@ -99,13 +107,11 @@ function hook_checklistapi_checklist_info() {
* Alter checklist definitions. * Alter checklist definitions.
* *
* This hook is invoked by checklistapi_get_checklist_info(). The checklist * This hook is invoked by checklistapi_get_checklist_info(). The checklist
* definitions are passed in by reference. Each element of the $checklists array * definitions are passed in by reference. Additional checklists may be added,
* is one returned by a module from checklistapi_get_checklist_info(). * or existing checklists may be altered or removed.
* Additional checklists may be added, or existing checklists may be altered or
* removed.
* *
* @param array $checklists * @param array $definitions
* A multidimensional array of checklists definitions returned from * The multidimensional array of checklist definitions returned by
* hook_checklistapi_checklist_info(). * hook_checklistapi_checklist_info().
* *
* For a working example, see checklistapi_example.module. * For a working example, see checklistapi_example.module.
...@@ -113,13 +119,20 @@ function hook_checklistapi_checklist_info() { ...@@ -113,13 +119,20 @@ function hook_checklistapi_checklist_info() {
* @see checklistapi_get_checklist_info() * @see checklistapi_get_checklist_info()
* @see hook_checklistapi_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. // Add an item.
$checklists['example']['example_group']['sample_item'] = array( $definitions['example_checklist']['example_group']['new_item'] = array(
'title' => t('Sample item'), '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. // Remove an item.
unset($checklists['example']['example_group']['example_item']); unset($definitions['example_checklist']['example_group']['example_item_2']);
} }
/** /**
......
...@@ -14,12 +14,14 @@ ...@@ -14,12 +14,14 @@
define('CHECKLISTAPI_LINK_CONTEXT_ANY', 1); 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); 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); define('CHECKLISTAPI_LINK_CONTEXT_ITEM_UNCHECKED', 3);
......
...@@ -16,8 +16,8 @@ function checklistapi_example_checklistapi_checklist_info() { ...@@ -16,8 +16,8 @@ function checklistapi_example_checklistapi_checklist_info() {
$checklists = array(); $checklists = array();
$checklists['example_checklist'] = array( $checklists['example_checklist'] = array(
'#title' => t('Checklist API example'), '#title' => t('Checklist API example'),
'#description' => t('An example implementation of the Checklist API.'),
'#path' => 'admin/config/development/checklistapi-example', '#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>'), '#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( 'i_suck' => array(
'#title' => t('I suck'), '#title' => t('I suck'),
......
...@@ -92,8 +92,8 @@ class ChecklistapiChecklist { ...@@ -92,8 +92,8 @@ class ChecklistapiChecklist {
$this->items[$group_key] = $definition[$group_key]; $this->items[$group_key] = $definition[$group_key];
unset($definition[$group_key]); unset($definition[$group_key]);
} }
foreach ($definition as $key => $value) { foreach ($definition as $property_key => $value) {
$property_name = checklistapi_strtolowercamel(drupal_substr($key, 1)); $property_name = checklistapi_strtolowercamel(drupal_substr($property_key, 1));
$this->$property_name = $value; $this->$property_name = $value;
} }
$this->savedProgress = variable_get($this->getSavedProgressVariableName(), array()); $this->savedProgress = variable_get($this->getSavedProgressVariableName(), array());
...@@ -135,7 +135,9 @@ class ChecklistapiChecklist { ...@@ -135,7 +135,9 @@ class ChecklistapiChecklist {
* Saves checklist progress to a Drupal variable. * Saves checklist progress to a Drupal variable.
* *
* @param array $values * @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) { public function saveProgress(array $values) {
global $user; global $user;
......
...@@ -12,8 +12,8 @@ function checklistapi_test_checklistapi_checklist_info() { ...@@ -12,8 +12,8 @@ function checklistapi_test_checklistapi_checklist_info() {
$checklists = array(); $checklists = array();
$checklists['test_checklist'] = array( $checklists['test_checklist'] = array(
'#title' => t('Checklist API test'), '#title' => t('Checklist API test'),
'#description' => t('A test checklist.'),
'#path' => 'admin/config/development/checklistapi-test', '#path' => 'admin/config/development/checklistapi-test',
'#description' => t('A test checklist.'),
'#help' => t('<p>This is a test checklist.</p>'), '#help' => t('<p>This is a test checklist.</p>'),
'group_two' => array( 'group_two' => array(
'#title' => t('Group two'), '#title' => t('Group two'),
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment