Commit 72f97d9a authored by jhodgdon's avatar jhodgdon

Issue #1500160 by jmarkel, tstoeckler: Better documentation for...

Issue #1500160 by jmarkel, tstoeckler: Better documentation for hook_block_info, especially the pages component
parent 4b3298eb
......@@ -20,11 +20,11 @@
* identifier referred to as "delta" (the array key in the return value). Delta
* values only need to be unique within your module, and they are used in the
* following ways:
* - Passed into the other block hooks in your module as an argument to
* identify the block being configured or viewed.
* - Passed into the other block hooks in your module as an argument to identify
* the block being configured or viewed.
* - Used to construct the default HTML ID of "block-MODULE-DELTA" applied to
* each block when it is rendered (which can then be used for CSS styling or
* JavaScript programming).
* each block when it is rendered. This ID may then be used for CSS styling or
* JavaScript programming.
* - Used to define a theming template suggestion of block__MODULE__DELTA, for
* advanced theming possibilities.
* - Used by other modules to identify your block in hook_block_info_alter() and
......@@ -39,10 +39,10 @@
* An associative array whose keys define the delta for each block and whose
* values contain the block descriptions. Each block description is itself an
* associative array, with the following key-value pairs:
* - 'info': (required) The human-readable administrative name of the block.
* - info: (required) The human-readable administrative name of the block.
* This is used to identify the block on administration screens, and
* is not displayed to non-administrative users.
* - 'cache': (optional) A bitmask describing what kind of caching is
* - cache: (optional) A bitmask describing what kind of caching is
* appropriate for the block. Drupal provides the following bitmask
* constants for defining cache granularity:
* - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
......@@ -56,28 +56,28 @@
* - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
* page where it is visible.
* - DRUPAL_NO_CACHE: The block should not get cached.
* - 'properties': (optional) Array of additional metadata to add to the
* block. Common properties include:
* - 'administrative': Boolean which categorizes this block as usable in
* an administrative context. This might include blocks which help an
* administrator approve/deny comments, or view recently created
* user accounts.
* - 'weight': (optional) Initial value for the ordering weight of this block.
* - properties: (optional) Array of additional metadata to add to the block.
* Common properties include:
* - administrative: Boolean that categorizes this block as usable in an
* administrative context. This might include blocks that help an
* administrator approve/deny comments, or view recently created user
* accounts.
* - weight: (optional) Initial value for the ordering weight of this block.
* Most modules do not provide an initial value, and any value provided can
* be modified by a user on the block configuration screen.
* - 'status': (optional) Initial value for block enabled status. (1 =
* enabled, 0 = disabled). An initial value for 'region' is required for
* 'status' to take effect.
* - status: (optional) Initial value for block enabled status. (1 = enabled,
* 0 = disabled). An initial value for 'region' is required for 'status' to
* take effect.
* Most modules do not provide an initial value, and any value provided can
* be modified by a user on the block configuration screen.
* - 'region': (optional) Initial value for theme region within which this
* block is set. If the specified region is not available in a theme, the
* block will be disabled. The initial value for 'status' must be enabled or
* the initial region value is ignored.
* - region: (optional) Initial value for theme region within which this block
* is set. If the specified region is not available in a theme, the block
* will be disabled. The initial value for 'status' must be enabled or the
* initial region value is ignored.
* Most modules do not provide an initial value, and any value provided can
* be modified by a user on the block configuration screen.
* - 'visibility': (optional) Initial value for the visibility flag, which
* tells how to interpret the 'pages' value. Possible values are:
* - visibility: (optional) Initial value for the visibility flag, which tells
* how to interpret the 'pages' value. Possible values are:
* - BLOCK_VISIBILITY_NOTLISTED: Show on all pages except listed pages.
* 'pages' lists the paths where the block should not be shown.
* - BLOCK_VISIBILITY_LISTED: Show only on listed pages. 'pages' lists the
......@@ -87,7 +87,14 @@
* Most modules do not provide an initial value for 'visibility' or 'pages',
* and any value provided can be modified by a user on the block
* configuration screen.
* - 'pages': (optional) See 'visibility' above.
* - pages: (optional) See 'visibility' above. A string that contains one or
* more page paths separated by '\n', '\r', or '\r\n' when 'visibility' is
* set to BLOCK_VISIBILITY_NOTLISTED or BLOCK_VISIBILITY_LISTED, or custom
* PHP code when 'visibility' is set to BLOCK_VISIBILITY_PHP. Paths may use
* '*' as a wildcard (matching any number of characters); '<front>'
* designates the site's front page. For BLOCK_VISIBILITY_PHP, the PHP
* code's return value should be TRUE if the block is to be made visible or
* FALSE if the block should not be visible.
*
* For a detailed usage example, see block_example.module.
*
......
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