Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Issue #1323720 by xenophyle, xjm: Clean up API docs for block module.

merge-requests/26/head
webchick 2011-12-24 17:51:06 -08:00
parent 0dc3499883
commit 755e486d12
4 changed files with 63 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
modules/block/block-admin-display-form.tpl.php
View File

@ -21,6 +21,8 @@
* *
* @see template_preprocess_block_admin_display_form() * @see template_preprocess_block_admin_display_form()
* @see theme_block_admin_display() * @see theme_block_admin_display()
*
* @ingroup themeable
*/ */
?> ?>
<?php <?php

25
modules/block/block.admin.inc
View File

@ -57,7 +57,7 @@ function block_admin_display_prepare_blocks($theme) {
} }
/** /**
* Form builder for the main blocks administration form. * Form constructor for the main block administration form.
* *
* @param $blocks * @param $blocks
* An array of blocks, as returned by block_admin_display_prepare_blocks(). * An array of blocks, as returned by block_admin_display_prepare_blocks().
@ -165,7 +165,7 @@ function block_admin_display_form($form, &$form_state, $blocks, $theme, $block_r
} }
/** /**
* Form submission handler for the main blocks administration form. * Form submission handler for block_admin_display_form().
* *
* @see block_admin_display_form() * @see block_admin_display_form()
*/ */
@ -197,10 +197,9 @@ function block_admin_display_form_submit($form, &$form_state) {
} }
/** /**
* Helper function for sorting blocks on admin/structure/block. * Sorts active blocks by region, then by weight; sorts inactive blocks by name.
* *
* Active blocks are sorted by region, then by weight. * Callback for usort() in block_admin_display_prepare_blocks().
* Disabled blocks are sorted by name.
*/ */
function _block_compare($a, $b) { function _block_compare($a, $b) {
global $theme_key; global $theme_key;
@ -240,7 +239,7 @@ function _block_compare($a, $b) {
} }
/** /**
* Form builder for the block configuration form. * Form constructor for the block configuration form.
* *
* Also used by block_add_block_form() for adding a new custom block. * Also used by block_add_block_form() for adding a new custom block.
* *
@ -441,7 +440,7 @@ function block_admin_configure($form, &$form_state, $module, $delta) {
} }
/** /**
* Form validation handler for the block configuration form. * Form validation handler for block_admin_configure().
* *
* @see block_admin_configure() * @see block_admin_configure()
* @see block_admin_configure_submit() * @see block_admin_configure_submit()
@ -459,7 +458,7 @@ function block_admin_configure_validate($form, &$form_state) {
} }
/** /**
* Form submission handler for the block configuration form. * Form submission handler for block_admin_configure().
* *
* @see block_admin_configure() * @see block_admin_configure()
* @see block_admin_configure_validate() * @see block_admin_configure_validate()
@ -519,7 +518,7 @@ function block_admin_configure_submit($form, &$form_state) {
} }
/** /**
* Form builder for the add block form. * Form constructor for the add block form.
* *
* @see block_add_block_form_validate() * @see block_add_block_form_validate()
* @see block_add_block_form_submit() * @see block_add_block_form_submit()
@ -530,7 +529,7 @@ function block_add_block_form($form, &$form_state) {
} }
/** /**
* Form validation handler for the add block form. * Form validation handler for block_add_block_form().
* *
* @see block_add_block_form() * @see block_add_block_form()
* @see block_add_block_form_submit() * @see block_add_block_form_submit()
@ -544,7 +543,7 @@ function block_add_block_form_validate($form, &$form_state) {
} }
/** /**
* Form submission handler for the add block form. * Form submission handler for block_add_block_form().
* *
* Saves the new custom block. * Saves the new custom block.
* *
@ -609,7 +608,7 @@ function block_add_block_form_submit($form, &$form_state) {
} }
/** /**
* Form builder for the custom block deletion form. * Form constructor for the custom block deletion form.
* *
* @param $module * @param $module
* The name of the module that implements the block to be deleted. This should * The name of the module that implements the block to be deleted. This should
@ -629,7 +628,7 @@ function block_custom_block_delete($form, &$form_state, $module, $delta) {
} }
/** /**
* Form submission handler for the custom block deletion form. * Form submission handler for block_custom_block_delete().
* *
* @see block_custom_block_delete() * @see block_custom_block_delete()
*/ */

65
modules/block/block.module
View File

@ -16,27 +16,27 @@ define('BLOCK_REGION_NONE', -1);
define('BLOCK_CUSTOM_FIXED', 0); define('BLOCK_CUSTOM_FIXED', 0);
/** /**
* Show this block by default, but let individual users hide it. * Shows this block by default, but lets individual users hide it.
*/ */
define('BLOCK_CUSTOM_ENABLED', 1); define('BLOCK_CUSTOM_ENABLED', 1);
/** /**
* Hide this block by default but let individual users show it. * Hides this block by default but lets individual users show it.
*/ */
define('BLOCK_CUSTOM_DISABLED', 2); define('BLOCK_CUSTOM_DISABLED', 2);
/** /**
* Show this block on every page except the listed pages. * Shows this block on every page except the listed pages.
*/ */
define('BLOCK_VISIBILITY_NOTLISTED', 0); define('BLOCK_VISIBILITY_NOTLISTED', 0);
/** /**
* Show this block on only the listed pages. * Shows this block on only the listed pages.
*/ */
define('BLOCK_VISIBILITY_LISTED', 1); define('BLOCK_VISIBILITY_LISTED', 1);
/** /**
* Show this block if the associated PHP code returns TRUE. * Shows this block if the associated PHP code returns TRUE.
*/ */
define('BLOCK_VISIBILITY_PHP', 2); define('BLOCK_VISIBILITY_PHP', 2);
@ -249,7 +249,7 @@ function block_block_view($delta = '') {
/** /**
* Implements hook_page_build(). * Implements hook_page_build().
* *
* Render blocks into their regions. * Renders blocks into their regions.
*/ */
function block_page_build(&$page) { function block_page_build(&$page) {
global $theme; global $theme;
@ -305,10 +305,13 @@ function block_page_build(&$page) {
} }
/** /**
* Get a renderable array of a region containing all enabled blocks. * Gets a renderable array of a region containing all enabled blocks.
* *
* @param $region * @param $region
* The requested region. * The requested region.
*
* @return
* A renderable array of a region containing all enabled blocks.
*/ */
function block_get_blocks_by_region($region) { function block_get_blocks_by_region($region) {
$build = array(); $build = array();
@ -319,10 +322,11 @@ function block_get_blocks_by_region($region) {
} }
/** /**
* Get an array of blocks suitable for drupal_render(). * Gets an array of blocks suitable for drupal_render().
* *
* @param $list * @param $list
* A list of blocks such as that returned by block_list(). * A list of blocks such as that returned by block_list().
*
* @return * @return
* A renderable array. * A renderable array.
*/ */
@ -353,7 +357,7 @@ function _block_get_renderable_array($list = array()) {
} }
/** /**
* Update the 'block' DB table with the blocks currently exported by modules. * Updates the 'block' DB table with the blocks currently exported by modules.
* *
* @param $theme * @param $theme
* The theme to rehash blocks for. If not provided, defaults to the currently * The theme to rehash blocks for. If not provided, defaults to the currently
@ -473,6 +477,7 @@ function _block_rehash($theme = NULL) {
* *
* @param $bid * @param $bid
* ID of the block to get information for. * ID of the block to get information for.
*
* @return * @return
* Associative array of information stored in the database for this block. * Associative array of information stored in the database for this block.
* Array keys: * Array keys:
@ -486,7 +491,14 @@ function block_custom_block_get($bid) {
} }
/** /**
* Define the custom block form. * Form constructor for the custom block form.
*
* @param $edit
* (optional) An associative array of information retrieved by
* block_custom_get_block() if an existing block is being edited, or an empty
* array otherwise. Defaults to array().
*
* @ingroup forms
*/ */
function block_custom_block_form($edit = array()) { function block_custom_block_form($edit = array()) {
$edit += array( $edit += array(
@ -528,6 +540,7 @@ function block_custom_block_form($edit = array()) {
* - format: Filter ID of the filter format for the body. * - format: Filter ID of the filter format for the body.
* @param $delta * @param $delta
* Block ID of the block to save. * Block ID of the block to save.
*
* @return * @return
* Always returns TRUE. * Always returns TRUE.
*/ */
@ -544,7 +557,7 @@ function block_custom_block_save($edit, $delta) {
} }
/** /**
* Implements hook_form_FORM_ID_alter(). * Implements hook_form_FORM_ID_alter() for user_profile_form().
*/ */
function block_form_user_profile_form_alter(&$form, &$form_state) { function block_form_user_profile_form_alter(&$form, &$form_state) {
if ($form['#user_category'] == 'account') { if ($form['#user_category'] == 'account') {
@ -588,7 +601,10 @@ function block_user_presave(&$edit, $account, $category) {
} }
/** /**
* Initialize blocks for enabled themes. * Initializes blocks for enabled themes.
*
* @param $theme_list
* An array of theme names.
*/ */
function block_themes_enabled($theme_list) { function block_themes_enabled($theme_list) {
foreach ($theme_list as $theme) { foreach ($theme_list as $theme) {
@ -597,7 +613,7 @@ function block_themes_enabled($theme_list) {
} }
/** /**
* Assign an initial, default set of blocks for a theme. * Assigns an initial, default set of blocks for a theme.
* *
* This function is called the first time a new theme is enabled. The new theme * This function is called the first time a new theme is enabled. The new theme
* gets a copy of the default theme's blocks, with the difference that if a * gets a copy of the default theme's blocks, with the difference that if a
@ -628,7 +644,7 @@ function block_theme_initialize($theme) {
} }
/** /**
* Return all blocks in the specified region for the current user. * Returns all blocks in the specified region for the current user.
* *
* @param $region * @param $region
* The name of a region. * The name of a region.
@ -640,7 +656,7 @@ function block_theme_initialize($theme) {
* empty to see how many columns are going to be displayed. * empty to see how many columns are going to be displayed.
* *
* @todo * @todo
* Now that the blocks table has a primary key, we should use that as the * Now that the block table has a primary key, we should use that as the
* array key instead of MODULE_DELTA. * array key instead of MODULE_DELTA.
*/ */
function block_list($region) { function block_list($region) {
@ -662,7 +678,7 @@ function block_list($region) {
} }
/** /**
* Load a block object from the database. * Loads a block object from the database.
* *
* @param $module * @param $module
* Name of the module that implements the block to load. * Name of the module that implements the block to load.
@ -690,7 +706,10 @@ function block_load($module, $delta) {
} }
/** /**
* Load blocks information from the database. * Loads blocks' information from the database.
*
* @return
* An array of blocks grouped by region.
*/ */
function _block_load_blocks() { function _block_load_blocks() {
global $theme_key; global $theme_key;
@ -721,8 +740,8 @@ function _block_load_blocks() {
/** /**
* Implements hook_block_list_alter(). * Implements hook_block_list_alter().
* *
* Check the page, user role and user specific visibilty settings. * Checks the page, user role, and user-specific visibilty settings.
* Remove the block if the visibility conditions are not met. * Removes the block if the visibility conditions are not met.
*/ */
function block_block_list_alter(&$blocks) { function block_block_list_alter(&$blocks) {
global $user, $theme_key; global $user, $theme_key;
@ -916,9 +935,9 @@ function block_flush_caches() {
} }
/** /**
* Process variables for block.tpl.php * Processes variables for block.tpl.php.
* *
* Prepare the values passed to the theme_block function to be passed * Prepares the values passed to the theme_block function to be passed
* into a pluggable template engine. Uses block properties to generate a * into a pluggable template engine. Uses block properties to generate a
* series of template file suggestions. If none are found, the default * series of template file suggestions. If none are found, the default
* block.tpl.php is used. * block.tpl.php is used.
@ -967,7 +986,7 @@ function template_preprocess_block(&$variables) {
/** /**
* Implements hook_user_role_delete(). * Implements hook_user_role_delete().
* *
* Remove deleted role from blocks that use it. * Removes deleted role from blocks that use it.
*/ */
function block_user_role_delete($role) { function block_user_role_delete($role) {
db_delete('block_role') db_delete('block_role')
@ -1019,7 +1038,7 @@ function block_admin_paths() {
/** /**
* Implements hook_modules_uninstalled(). * Implements hook_modules_uninstalled().
* *
* Cleanup {block} and {block_role} tables from modules' blocks. * Cleans up {block} and {block_role} tables from modules' blocks.
*/ */
function block_modules_uninstalled($modules) { function block_modules_uninstalled($modules) {
db_delete('block') db_delete('block')

11
modules/block/block.tpl.php
View File

@ -12,11 +12,12 @@
* - $block->region: The block region embedding the current block. * - $block->region: The block region embedding the current block.
* - $classes: String of classes that can be used to style contextually through * - $classes: String of classes that can be used to style contextually through
* CSS. It can be manipulated through the variable $classes_array from * CSS. It can be manipulated through the variable $classes_array from
* preprocess functions. The default values can be one or more of the following: * preprocess functions. The default values can be one or more of the
* following:
* - block: The current template type, i.e., "theming hook". * - block: The current template type, i.e., "theming hook".
* - block-[module]: The module generating the block. For example, the user module * - block-[module]: The module generating the block. For example, the user
* is responsible for handling the default user navigation block. In that case * module is responsible for handling the default user navigation block. In
* the class would be "block-user". * that case the class would be 'block-user'.
* - $title_prefix (array): An array containing additional output populated by * - $title_prefix (array): An array containing additional output populated by
* modules, intended to be displayed in front of the main title tag that * modules, intended to be displayed in front of the main title tag that
* appears in the template. * appears in the template.
@ -39,6 +40,8 @@
* @see template_preprocess() * @see template_preprocess()
* @see template_preprocess_block() * @see template_preprocess_block()
* @see template_process() * @see template_process()
*
* @ingroup themeable
*/ */
?> ?>
<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>> <div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>