From b40facf07f25c5805f89d3d617e6e55dbadc900d Mon Sep 17 00:00:00 2001 From: Jennifer Hodgdon Date: Thu, 29 Mar 2012 13:42:42 -0700 Subject: Issue #1500160 by jmarkel, tstoeckler: Fix up docs for hook_block_info --- modules/block/block.api.php | 73 +++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 33 deletions(-) (limited to 'modules/block') diff --git a/modules/block/block.api.php b/modules/block/block.api.php index d33f59425..3cd52f8b7 100644 --- a/modules/block/block.api.php +++ b/modules/block/block.api.php @@ -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,43 +39,43 @@ * 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. - * 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 + * - 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 * 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 * roles the user viewing the page belongs to. * - DRUPAL_CACHE_PER_USER: The block can change depending on the user - * viewing the page. This setting can be resource-consuming for sites - * with large number of users, and should only be used when + * viewing the page. This setting can be resource-consuming for sites with + * large number of users, and should only be used when * DRUPAL_CACHE_PER_ROLE is not sufficient. - * - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page - * being viewed. - * - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every - * page where it is visible. + * - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page being + * viewed. + * - 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). 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. Most modules do not provide an initial value, and - * any value provided can be modified by a user on the block configuration - * screen. Note: If you set a region that isn't available in the currently - * enabled theme, the block will be disabled. - * - 'visibility': (optional) Initial value for the visibility flag, which - * tells how to interpret the 'pages' value. Possible values are: + * - status: (optional) Initial value for block enabled status. (1 = enabled, + * 0 = disabled). 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. Most modules do not provide an initial value, and any value + * provided can be modified by a user on the block configuration screen. + * Note: If you set a region that isn't available in the currently enabled + * theme, the block will be disabled. + * - 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 @@ -85,7 +85,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); '' + * 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. * -- cgit v1.2.3