hook_block

developer/hooks/core.php, строка 169

Версии
5 – 6: hook_block($op = 'list', $delta = 0, $edit = array())

Определяет блок или набор блоков.

Любой модуль может добавить свои блоки, определив их в hook_block. Этот хук вызывается в theme.inc при отображении блоков, а также в block.module для показа списка доступных блоков.

После завершения написания ваших блоков, не забывайте включить их в разделе администрирования блоков на сайте.

Подробный пример использования можно посмотреть в block_example.module.

Параметры

$op Какого рода информацию о блоках требуется вернуть. Возможные значения:

'list': Список всех блоков данного модуля.
'configure': Форм настроек для блока.
'save': Сохранить настройки блока.
'view': Требуется вернуть содержимое блока для отображения в нужном разделе страницы.

$delta Информацию о каком блоке нужно вернуть (для всех операций $op кроме 'list'). Хотя чаще всего блоки нумеруются целыми числами начиная с нуля , но это не обязательно. К примеру, модуль aggregator.module использует строки в качестве значений $delta.

$edit Если $op равно 'save', в этом параметре хранятся данные из формы настройки. В остальных случаях массив пуст.

Возвращаемое значение

$op = 'list': Массив с описаниями всех блоков модуля. Каждое из описаний это ассоциативный массив с такими ключами:
- 'info': (обязательно) Имя блока для отображения в административном интерфейсе.
- 'cache': Флаги, описывающае поведение блока с точки зрения системы кеширования. Модуль block.module определяет таки флаги:
  - BLOCK_CACHE_PER_ROLE (значение по умолчанию): Содержимое блока меняется в зависимости от роли пользователя, просматривающего его.
  - BLOCK_CACHE_PER_USER: Содержимое блока меняется в зависимости от пользователя, просматривающего блок. Блок с этим флагом может потребовать очень много ресурсов для отображения, особенно для крупных сайтом, поэтому этот флаг стоит использовать только в случае, если флаг BLOCK_CACHE_PER_ROLE использовать нельзя.
  - BLOCK_CACHE_PER_PAGE: Содержимое блока меняется в зависимости от страницы, на которой он отображается.
  - BLOCK_CACHE_GLOBAL: Содержимое блока не зависит ни от пользователя, просматривающего блок, ни от страницы, на которой блок отображен.
  - BLOCK_NO_CACHE: Блок не нужно кешировать.
  Заметим, что для пользователя #1 блоки никогда не кешируются.
- 'weight', 'status', 'region', 'visibility', 'pages': Для блока (заданного параметром $delta) можно явно указать вес, включить/выключить его, ограничить отображение только на заданных страницах, и т.п. Эти установки вступят в действие при первом отображении блока в интерфейсе администрирования, после чего администратор сможет их изменить.
  
  Заметим, что если для блока задано отображение в области, отсутствующей в данной теме, блок будет помещен в область по умолчанию (первый элемент массива _regions в описании темы).
$op = 'configure': Необязательная форма настройки для блока.
$op = 'save': Ничего.
$op = 'view': Ассоциативный массив, описывающий блок (заданный параметром $delta). Ключ 'subject' этого массива должен задавать заголовок блока, а 'content' — его содержимое. Если значение 'content' будет пустым, блок не выведется, даже если 'subject' будет заполнен.

Declare a block or set of blocks.

Any module can export a block (or blocks) to be displayed by defining the _block hook. This hook is called by theme.inc to display a block, and also by block.module to procure the list of available blocks.

The functions mymodule_display_block_1 and 2, as used in the example, should of course be defined somewhere in your module and return the content you want to display to your users. If the "content" element is empty, no block will be displayed even if "subject" is present.

After completing your blocks, do not forget to enable them in the block admin menu.

For a detailed usage example, see block_example.module.

Parameters

$op What kind of information to retrieve about the block or blocks. Possible values:

'list': A list of all blocks defined by the module.
'configure': Configuration form for the block.
'save': Save the configuration options.
'view': Process the block when enabled in a region in order to view its contents.

$delta Which block to return (not applicable if $op is 'list'). Although it is most commonly an integer starting at 0, this is not mandatory. For instance, aggregator.module uses string values for $delta

$edit If $op is 'save', the submitted form data from the configuration form.

Return value

If $op is 'list': An array of block descriptions. Each block description is an associative array, with the following key-value pairs:
- 'info': (required) The human-readable name of the block.
- 'cache': A bitmask of flags describing how the block should behave with respect to block caching. The following shortcut bitmasks are provided as constants in block.module:
  - BLOCK_CACHE_PER_ROLE (default): The block can change depending on the roles the user viewing the page belongs to.
  - BLOCK_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 BLOCK_CACHE_PER_ROLE is not sufficient.
  - BLOCK_CACHE_PER_PAGE: The block can change depending on the page being viewed.
  - BLOCK_CACHE_GLOBAL: The block is the same for every user on every page where it is visible.
  - BLOCK_NO_CACHE: The block should not get cached.
- 'weight', 'status', 'region', 'visibility', 'pages': You can give your blocks an explicit weight, enable them, limit them to given pages, etc. These settings will be registered when the block is first loaded at admin/block, and from there can be changed manually via block administration. Note that if you set a region that isn't available in a given theme, the block will be registered instead to that theme's default region (the first item in the _regions array).
- If $op is 'configure': optionally return the configuration form.
- If $op is 'save': return nothing.
- If $op is 'view': return an array which must define a 'subject' element and a 'content' element defining the block indexed by $delta.

Связанные темы

Код

<?php
function hook_block($op = 'list', $delta = 0, $edit = array()) {
  if ($op == 'list') {
    $blocks[0] = array('info' => t('Mymodule block #1 shows ...'),
      'weight' => 0, 'status' => 1, 'region' => 'left');
      // BLOCK_CACHE_PER_ROLE will be assumed for block 0.

    $blocks[1] = array('info' => t('Mymodule block #2 describes ...'),
      'cache' => BLOCK_CACHE_PER_ROLE | BLOCK_CACHE_PER_PAGE);

    return $blocks;
  }
  else if ($op == 'configure' && $delta == 0) {
    $form['items'] = array(
      '#type' => 'select',
      '#title' => t('Number of items'),
      '#default_value' => variable_get('mymodule_block_items', 0),
      '#options' => array('1', '2', '3'),
    );
    return $form;
  }
  else if ($op == 'save' && $delta == 0) {
    variable_set('mymodule_block_items', $edit['items']);
  }
  else if ($op == 'view') {
    switch($delta) {
      case 0:
        $block = array('subject' => t('Title of block #1'),
          'content' => mymodule_display_block_1());
        break;
      case 1:
        $block = array('subject' => t('Title of block #2'),
          'content' => mymodule_display_block_2());
        break;
    }
    return $block;
  }
}
?>

Пользовательские комментарии

#1 2010-07-14, rish-vitalio

$block = array('subject' => t('Title of block #2'),
'content' => mymodule_display_block_2());
что значит "mymodule_display_block_2());"?????????
и как ее лучше описать?

#2 2011-01-15, VladSavitsky

mymodule_display_block_2() - это функция, которая создает и возвращает контент блока.

Войдите или зарегистрируйтесь, чтобы получить возможность отправлять комментарии