Issue #1323720 by xenophyle: Clean up API docs for block module.
catch
parent
e6ae6a89dc
commit
90597a5ff9
|
|
@ -21,6 +21,8 @@
|
|||
*
|
||||
* @see template_preprocess_block_admin_display_form()
|
||||
* @see theme_block_admin_display()
|
||||
*
|
||||
* @ingroup themeable
|
||||
*/
|
||||
?>
|
||||
<?php
|
||||
|
|
|
|||
|
|
@ -6,7 +6,11 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* Menu callback for admin/structure/block/demo.
|
||||
* Page callback: Attaches CSS for the block region demo.
|
||||
*
|
||||
* Path: admin/structure/block/demo/% (for each theme)
|
||||
*
|
||||
* @see block_menu()
|
||||
*/
|
||||
function block_admin_demo($theme = NULL) {
|
||||
drupal_add_css(drupal_get_path('module', 'block') . '/block.admin.css');
|
||||
|
|
@ -14,11 +18,15 @@ function block_admin_demo($theme = NULL) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Menu callback for admin/structure/block.
|
||||
* Page callback: Shows the block administration page.
|
||||
*
|
||||
* Path: admin/structure/block
|
||||
*
|
||||
* @param $theme
|
||||
* The theme to display the administration page for. If not provided, defaults
|
||||
* to the currently used theme.
|
||||
*
|
||||
* @see block_menu()
|
||||
*/
|
||||
function block_admin_display($theme = NULL) {
|
||||
global $theme_key;
|
||||
|
|
@ -57,7 +65,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
|
||||
* An array of blocks, as returned by block_admin_display_prepare_blocks().
|
||||
|
|
@ -165,7 +173,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()
|
||||
*/
|
||||
|
|
@ -197,10 +205,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.
|
||||
* Disabled blocks are sorted by name.
|
||||
* Callback for usort() in block_admin_display_prepare_blocks().
|
||||
*/
|
||||
function _block_compare($a, $b) {
|
||||
global $theme_key;
|
||||
|
|
@ -240,7 +247,9 @@ function _block_compare($a, $b) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Form builder for the block configuration form.
|
||||
* Page callback: Form constructor for the block configuration form.
|
||||
*
|
||||
* Path: admin/structure/block/manage/%/%
|
||||
*
|
||||
* Also used by block_add_block_form() for adding a new custom block.
|
||||
*
|
||||
|
|
@ -249,6 +258,7 @@ function _block_compare($a, $b) {
|
|||
* @param $delta
|
||||
* Unique ID of the block within the context of $module.
|
||||
*
|
||||
* @see block_menu()
|
||||
* @see block_admin_configure_validate()
|
||||
* @see block_admin_configure_submit()
|
||||
* @ingroup forms
|
||||
|
|
@ -441,7 +451,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_submit()
|
||||
|
|
@ -459,7 +469,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_validate()
|
||||
|
|
@ -519,8 +529,11 @@ function block_admin_configure_submit($form, &$form_state) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Form builder for the add block form.
|
||||
* Page callback: Form constructor for the add block form.
|
||||
*
|
||||
* Path: admin/structure/block/add
|
||||
*
|
||||
* @see block_menu()
|
||||
* @see block_add_block_form_validate()
|
||||
* @see block_add_block_form_submit()
|
||||
* @ingroup forms
|
||||
|
|
@ -530,7 +543,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_submit()
|
||||
|
|
@ -544,7 +557,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.
|
||||
*
|
||||
|
|
@ -609,7 +622,9 @@ function block_add_block_form_submit($form, &$form_state) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Form builder for the custom block deletion form.
|
||||
* Page callback: Form constructor for the custom block deletion form.
|
||||
*
|
||||
* Path: admin/structure/block/manage/%/%/delete
|
||||
*
|
||||
* @param $module
|
||||
* The name of the module that implements the block to be deleted. This should
|
||||
|
|
@ -617,6 +632,7 @@ function block_add_block_form_submit($form, &$form_state) {
|
|||
* @param $delta
|
||||
* The unique ID of the block within the context of $module.
|
||||
*
|
||||
* @see block_menu()
|
||||
* @see block_custom_block_delete_submit()
|
||||
*/
|
||||
function block_custom_block_delete($form, &$form_state, $module, $delta) {
|
||||
|
|
@ -629,7 +645,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()
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -16,27 +16,27 @@ define('BLOCK_REGION_NONE', -1);
|
|||
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);
|
||||
|
||||
/**
|
||||
* 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);
|
||||
|
||||
/**
|
||||
* 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);
|
||||
|
||||
/**
|
||||
* Show this block on only the listed pages.
|
||||
* Shows this block on only the listed pages.
|
||||
*/
|
||||
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);
|
||||
|
||||
|
|
@ -177,21 +177,35 @@ function block_menu() {
|
|||
}
|
||||
|
||||
/**
|
||||
* Menu item access callback - only admin or enabled themes can be accessed.
|
||||
* Access callback: Only admin or enabled themes can be accessed.
|
||||
*
|
||||
* Path:
|
||||
* - admin/structure/block/list/% (for each theme)
|
||||
* - admin/structure/block/demo/% (for each theme)
|
||||
*
|
||||
* @param $theme
|
||||
* Either the name of a theme or a full theme object.
|
||||
*
|
||||
* @see block_menu()
|
||||
*/
|
||||
function _block_themes_access($theme) {
|
||||
return user_access('administer blocks') && drupal_theme_access($theme);
|
||||
}
|
||||
|
||||
/**
|
||||
* Theme callback for the block configuration pages.
|
||||
* Theme callback: Uses the theme specified in the parameter.
|
||||
*
|
||||
* Path: admin/structure/block/demo/% (for each theme)
|
||||
*
|
||||
* @param $theme
|
||||
* The theme whose blocks are being configured. If not set, the default theme
|
||||
* is assumed.
|
||||
*
|
||||
* @return
|
||||
* The theme that should be used for the block configuration page, or NULL
|
||||
* to indicate that the default theme should be used.
|
||||
*
|
||||
* @see block_menu()
|
||||
*/
|
||||
function _block_custom_theme($theme = NULL) {
|
||||
// We return exactly what was passed in, to guarantee that the page will
|
||||
|
|
@ -249,7 +263,7 @@ function block_block_view($delta = '') {
|
|||
/**
|
||||
* Implements hook_page_build().
|
||||
*
|
||||
* Render blocks into their regions.
|
||||
* Renders blocks into their regions.
|
||||
*/
|
||||
function block_page_build(&$page) {
|
||||
global $theme;
|
||||
|
|
@ -305,10 +319,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
|
||||
* The requested region.
|
||||
*
|
||||
* @return
|
||||
* A renderable array of a region containing all enabled blocks.
|
||||
*/
|
||||
function block_get_blocks_by_region($region) {
|
||||
$build = array();
|
||||
|
|
@ -319,10 +336,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
|
||||
* A list of blocks such as that returned by block_list().
|
||||
*
|
||||
* @return
|
||||
* A renderable array.
|
||||
*/
|
||||
|
|
@ -378,7 +396,7 @@ function _block_get_renderable_region($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
|
||||
* The theme to rehash blocks for. If not provided, defaults to the currently
|
||||
|
|
@ -498,6 +516,7 @@ function _block_rehash($theme = NULL) {
|
|||
*
|
||||
* @param $bid
|
||||
* ID of the block to get information for.
|
||||
*
|
||||
* @return
|
||||
* Associative array of information stored in the database for this block.
|
||||
* Array keys:
|
||||
|
|
@ -511,7 +530,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()) {
|
||||
$edit += array(
|
||||
|
|
@ -553,6 +579,7 @@ function block_custom_block_form($edit = array()) {
|
|||
* - format: Filter ID of the filter format for the body.
|
||||
* @param $delta
|
||||
* Block ID of the block to save.
|
||||
*
|
||||
* @return
|
||||
* Always returns TRUE.
|
||||
*/
|
||||
|
|
@ -569,7 +596,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) {
|
||||
$account = $form['#user'];
|
||||
|
|
@ -611,7 +638,10 @@ function block_user_presave(&$edit, $account) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Initialize blocks for enabled themes.
|
||||
* Initializes blocks for enabled themes.
|
||||
*
|
||||
* @param $theme_list
|
||||
* An array of theme names.
|
||||
*/
|
||||
function block_themes_enabled($theme_list) {
|
||||
foreach ($theme_list as $theme) {
|
||||
|
|
@ -620,7 +650,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
|
||||
* gets a copy of the default theme's blocks, with the difference that if a
|
||||
|
|
@ -651,7 +681,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
|
||||
* The name of a region.
|
||||
|
|
@ -663,7 +693,7 @@ function block_theme_initialize($theme) {
|
|||
* empty to see how many columns are going to be displayed.
|
||||
*
|
||||
* @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.
|
||||
*/
|
||||
function block_list($region) {
|
||||
|
|
@ -682,7 +712,7 @@ function block_list($region) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Load a block object from the database.
|
||||
* Loads a block object from the database.
|
||||
*
|
||||
* @param $module
|
||||
* Name of the module that implements the block to load.
|
||||
|
|
@ -710,7 +740,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() {
|
||||
global $theme_key;
|
||||
|
|
@ -742,8 +775,8 @@ function _block_load_blocks() {
|
|||
/**
|
||||
* Implements hook_block_list_alter().
|
||||
*
|
||||
* Check the page, user role and user specific visibilty settings.
|
||||
* Remove the block if the visibility conditions are not met.
|
||||
* Checks the page, user role, and user-specific visibilty settings.
|
||||
* Removes the block if the visibility conditions are not met.
|
||||
*/
|
||||
function block_block_list_alter(&$blocks) {
|
||||
global $user, $theme_key;
|
||||
|
|
@ -829,11 +862,13 @@ function block_block_list_alter(&$blocks) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Build the content and subject for a block. For cacheable blocks, this is
|
||||
* called during #pre_render.
|
||||
* Builds the content and subject for a block.
|
||||
*
|
||||
* For cacheable blocks, this is called during #pre_render.
|
||||
*
|
||||
* @param $element
|
||||
* A renderable array.
|
||||
*
|
||||
* @return
|
||||
* A renderable array.
|
||||
*/
|
||||
|
|
@ -898,9 +933,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
|
||||
* series of template file suggestions. If none are found, the default
|
||||
* block.tpl.php is used.
|
||||
|
|
@ -952,7 +987,7 @@ function template_preprocess_block(&$variables) {
|
|||
/**
|
||||
* 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) {
|
||||
db_delete('block_role')
|
||||
|
|
@ -989,7 +1024,7 @@ function block_admin_paths() {
|
|||
/**
|
||||
* 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) {
|
||||
db_delete('block')
|
||||
|
|
|
|||
|
|
@ -12,11 +12,12 @@
|
|||
* - $block->region: The block region embedding the current block.
|
||||
* - $classes: String of classes that can be used to style contextually through
|
||||
* 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-[module]: The module generating the block. For example, the user module
|
||||
* is responsible for handling the default user navigation block. In that case
|
||||
* the class would be "block-user".
|
||||
* - block-[module]: The module generating the block. For example, the user
|
||||
* module is responsible for handling the default user navigation block. In
|
||||
* that case the class would be 'block-user'.
|
||||
* - $title_prefix (array): An array containing additional output populated by
|
||||
* modules, intended to be displayed in front of the main title tag that
|
||||
* appears in the template.
|
||||
|
|
@ -39,6 +40,8 @@
|
|||
* @see template_preprocess()
|
||||
* @see template_preprocess_block()
|
||||
* @see template_process()
|
||||
*
|
||||
* @ingroup themeable
|
||||
*/
|
||||
?>
|
||||
<div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>
|
||||
|
|
|
|||
Loading…
Reference in New Issue