Commit f701acd9 authored by TravisCarden's avatar TravisCarden

Issue #2904660 by TravisCarden: Updated documentation for new...

Issue #2904660 by TravisCarden: Updated documentation for new callback_checklistapi_checklist_items() and converted checklistapiexample to use it.
parent a762bf7d
......@@ -16,7 +16,7 @@
* Any number of checklists can be defined in an implementation of this hook.
* Checklist API will register menu items and create permissions for each one.
*
* For a working example, see checklistapi_example.module.
* For a working example, see checklistapiexample.module.
*
* @return array
* An array of checklist definitions. Each definition is keyed by an arbitrary
......@@ -24,6 +24,10 @@
* checklist may contain the following key-value pairs:
* - #title: The title of the checklist.
* - #path: The Drupal path where the checklist will be accessed.
* - #callback: A callback to provide the checklist items. See
* callback_checklistapi_checklist_items(). (This value is technically
* optional in order to provide backward compatibility for modules using the
* deprecated method of defining checklist items right in this array.)
* - #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
......@@ -34,48 +38,68 @@
* - #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 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
* configuration setting 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.
* - #url: The link url as a \Drupal\Core\Url object.
* - #weight: (optional) A floating point number used to sort the list
* of items before being output. Lower numbers appear before higher
* numbers.
* - (deprecated) Any number of arrays representing groups of items, to be
* presented as vertical tabs. Use #callback instead.
*
* @see checklistapi_example_checklistapi_checklist_info()
* @see callback_checklistapi_checklist_items()
* @see hook_checklistapi_checklist_info_alter()
* @see checklistapiexample_checklistapi_checklist_info()
*/
function hook_checklistapi_checklist_info() {
$definitions = [];
$definitions['example_checklist'] = [
'#title' => t('Example checklist'),
'#path' => 'example-checklist',
'#callback' => 'callback_checklistapi_checklist_items',
'#description' => t('An example checklist.'),
'#help' => t('<p>This is an example checklist.</p>'),
];
return $definitions;
}
/**
* Define the checklist items for a given checklist.
*
* Declared in hook_checklistapi_checklist_info().
*
* @return array
* An array 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 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 configuration
* setting 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.
* - #url: The link url as a \Drupal\Core\Url object.
* - #weight: (optional) A floating point number used to sort the list of
* items before being output. Lower numbers appear before higher
* numbers.
*
* @see hook_checklistapi_checklist_info()
* @see checklistapiexample_checklistapi_checklist_items()
*/
function callback_checklistapi_checklist_items() {
return [
'example_group' => [
'#title' => t('Example group'),
'#description' => t('<p>Here are some example items.</p>'),
......@@ -91,7 +115,6 @@ function hook_checklistapi_checklist_info() {
],
],
];
return $definitions;
}
/**
......@@ -101,14 +124,12 @@ function hook_checklistapi_checklist_info() {
* definitions are passed in by reference. Additional checklists may be added,
* or existing checklists may be altered or removed.
*
* For a working example, see checklistapi_example.module.
*
* @param array $definitions
* The multidimensional array of checklist definitions returned by
* hook_checklistapi_checklist_info().
*
* @see checklistapi_get_checklist_info()
* @see hook_checklistapi_checklist_info()
* @see checklistapiexample_checklistapi_checklist_info_alter()
*/
function hook_checklistapi_checklist_info_alter(array &$definitions) {
// Add an item.
......
......@@ -19,8 +19,18 @@ function checklistapiexample_checklistapi_checklist_info() {
$definitions['example_checklist'] = [
'#title' => t('Checklist API example'),
'#path' => '/admin/config/development/checklistapi-example',
'#callback' => 'checklistapiexample_checklistapi_checklist_items',
'#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>'),
];
return $definitions;
}
/**
* Implements callback_checklistapi_checklist_items() for example_checklist.
*/
function checklistapiexample_checklistapi_checklist_items() {
return [
'i_suck' => [
'#title' => t('I suck'),
'#description' => t('<p>Gain these skills to pass the <em><a href="http://headrush.typepad.com/creating_passionate_users/2005/10/getting_users_p.html">suck threshold</a></em> and start being creative with Drupal.</p>'),
......@@ -201,7 +211,6 @@ function checklistapiexample_checklistapi_checklist_info() {
],
],
];
return $definitions;
}
/**
......
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