modules/block/block.api.php

<?php
// $Id: block.api.php,v 1.8 2009/08/31 17:06:08 dries Exp $

/**
 * @file
 * Hooks provided by the Block module.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Define all blocks provided by the module.
 *
 * 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.
 *
 * @return
 *   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 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 common.inc:
 *     - 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
 *       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_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).
 *
 * After completing your blocks, do not forget to enable them in the
 * block admin menu.
 *
 * For a detailed usage example, see block_example.module.
 */
function hook_block_info() {
  $blocks['exciting'] = array(
    'info' => t('An exciting block provided by Mymodule.'),
    'weight' => 0,
    'status' => 1,
    'region' => 'sidebar_first',
    // DRUPAL_CACHE_PER_ROLE will be assumed for block 0.
  );

  $blocks['amazing'] = array(
    'info' => t('An amazing block provided by Mymodule.'),
    'cache' => DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE,
  );

  return $blocks;
}

/**
 * Configuration form for the block.
 *
 * @param $delta
 *   Which block to return. This is a descriptive string used to identify
 *   blocks within each module and also within the theme system.
 *   The $delta for each block is defined within the array that your module
 *   returns when the hook_block_info() implementation is called.
 * @return
 *   Optionally return the configuration form.
 *
 * For a detailed usage example, see block_example.module.
 */
function hook_block_configure($delta = '') {
  if ($delta == 'exciting') {
    $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;
  }
}

/**
 * Save the configuration options.
 *
 * @param $delta
 *   Which block to save the settings for. This is a descriptive string used
 *   to identify blocks within each module and also within the theme system.
 *   The $delta for each block is defined within the array that your module
 *   returns when the hook_block_info() implementation is called.
 * @param $edit
 *   The submitted form data from the configuration form.
 *
 * For a detailed usage example, see block_example.module.
 */
function hook_block_save($delta = '', $edit = array()) {
  if ($delta == 'exciting') {
    variable_set('mymodule_block_items', $edit['items']);
  }
}

/**
 * Process the block when enabled in a region in order to view its contents.
 *
 * @param $delta
 *   Which block to return. This is a descriptive string used to identify
 *   blocks within each module and also within the theme system.
 *   The $delta for each block is defined within the array that your module
 *   returns when the hook_block_info() implementation is called.
 * @return
 *   An array which must define a 'subject' element and a 'content' element
 *   defining the block indexed by $delta.
 *
 * The functions mymodule_display_block_exciting and _amazing, 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.
 *
 * For a detailed usage example, see block_example.module.
 */
function hook_block_view($delta = '') {
  switch ($delta) {
    case 'exciting':
      $block = array(
        'subject' => t('Default title of the exciting block'),
        'content' => mymodule_display_block_exciting(),
      );
      break;

    case 'amazing':
      $block = array(
        'subject' => t('Default title of the amazing block'),
        'content' => mymodule_display_block_amazing(),
      );
      break;
  }
  return $block;
}

/**
 * Perform alterations to the content of a block.
 *
 * This hook allows you to modify any data returned by hook_block_view().
 *
 * Note that instead of hook_block_view_alter(), which is called for all
 * blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
 * specific block.
 *
 * @param $data
 *   An array of data, as returned from the hook_block_view() implementation of
 *   the module that defined the block:
 *   - subject: The localized title of the block.
 *   - content: Either a string or a renderable array representing the content
 *     of the block. You should check that the content is an array before trying
 *     to modify parts of the renderable structure.
 * @param $block
 *   The block object, as loaded from the database, having the main properties:
 *   - module: The name of the module that defined the block.
 *   - delta: The identifier for the block within that module, as defined within
 *     hook_block_info().
 *
 * @see hook_block_view_alter()
 * @see hook_block_view()
 */
function hook_block_view_alter(&$data, $block) {
  // Remove the contextual links on all blocks that provide them.
  if (is_array($data['content']) && isset($data['content']['#contextual_links'])) {
    unset($data['content']['#contextual_links']);
  }
  // Add a theme wrapper function defined by the current module to all blocks
  // provided by the "somemodule" module.
  if (is_array($data['content']) && $block->module == 'somemodule') {
    $data['content']['#theme_wrappers'][] = 'mymodule_special_block';
  }
}

/**
 * Perform alterations to a specific block.
 *
 * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
 * specific block, rather than implementing hook_block_view_alter().
 *
 * Note that this hook fires before hook_block_view_alter(). Therefore, all
 * implementations of hook_block_view_MODULE_DELTA_alter() will run before all
 * implementations of hook_block_view_alter(), regardless of the module order.
 *
 * @param $data
 *   An array of data, as returned from the hook_block_view() implementation of
 *   the module that defined the block:
 *   - subject: The localized title of the block.
 *   - content: Either a string or a renderable array representing the content
 *     of the block. You should check that the content is an array before trying
 *     to modify parts of the renderable structure.
 * @param $block
 *   The block object, as loaded from the database, having the main properties:
 *   - module: The name of the module that defined the block.
 *   - delta: The identifier for the block within that module, as defined within
 *     hook_block_info().
 *
 * @see hook_block_view_alter()
 * @see hook_block_view()
 */
function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
  // This code will only run for a specific block. For example, if MODULE_DELTA
  // in the function definition above is set to "mymodule_somedelta", the code
  // will only run on the "somedelta" block provided by the "mymodule" module.

  // Change the title of the "somedelta" block provided by the "mymodule"
  // module.
  $data['subject'] = t('New title of the block');
}

/**
 * Act on blocks prior to rendering.
 *
 * This hook allows you to add, remove or modify blocks in the block list. The
 * block list contains the block definitions not the rendered blocks. The blocks
 * are rendered after the modules have had a chance to manipulate the block
 * list.
 * Alternatively you can set $block->content here, which will override the
 * content of the block and prevent hook_block_view() from running.
 *
 * @param $blocks
 *   An array of $blocks, keyed by $bid
 *
 * This example shows how to achieve language specific visibility setting for
 * blocks.
 */
function hook_block_info_alter(&$blocks) {
  global $language, $theme_key;

  $result = db_query('SELECT module, delta, language FROM {my_table}');
  $block_languages = array();
  foreach ($result as $record) {
    $block_languages[$record->module][$record->delta][$record->language] = TRUE;
  }

  foreach ($blocks as $key => $block) {
    // Any module using this alter should inspect the data before changing it,
    // to ensure it is what they expect.
    if ($block->theme != $theme_key || $block->status != 1) {
      // This block was added by a contrib module, leave it in the list.
      continue;
    }

    if (!isset($block_languages[$block->module][$block->delta])) {
      // No language setting for this block, leave it in the list.
      continue;
    }

    if (!isset($block_languages[$block->module][$block->delta][$language->language])) {
      // This block should not be displayed with the active language, remove
      // from the list.
      unset($blocks[$key]);
    }
  }
}

/**
 * @} End of "addtogroup hooks".
 */
1	<?php
2	// $Id: block.api.php,v 1.8 2009/08/31 17:06:08 dries Exp $
3
4	/**
5	* @file
6	* Hooks provided by the Block module.
7	*/
8
9	/**
10	* @addtogroup hooks
11	* @{
12	*/
13
14	/**
15	* Define all blocks provided by the module.
16	*
17	* Any module can export a block (or blocks) to be displayed by defining
18	* the _block hook. This hook is called by theme.inc to display a block,
19	* and also by block.module to procure the list of available blocks.
20	*
21	* @return
22	* An associative array whose keys define the $delta
23	* for each block and whose values contain the block descriptions. Each
24	* block description is itself an associative array, with the following
25	* key-value pairs:
26	* - 'info': (required) The human-readable name of the block.
27	* - 'cache': A bitmask of flags describing how the block should behave with
28	* respect to block caching. The following shortcut bitmasks are provided
29	* as constants in common.inc:
30	* - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
31	* roles the user viewing the page belongs to.
32	* - DRUPAL_CACHE_PER_USER: The block can change depending on the user
33	* viewing the page. This setting can be resource-consuming for sites
34	* with large number of users, and should only be used when
35	* DRUPAL_CACHE_PER_ROLE is not sufficient.
36	* - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page
37	* being viewed.
38	* - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
39	* page where it is visible.
40	* - DRUPAL_NO_CACHE: The block should not get cached.
41	* - 'weight', 'status', 'region', 'visibility', 'pages':
42	* You can give your blocks an explicit weight, enable them, limit them to
43	* given pages, etc. These settings will be registered when the block is first
44	* loaded at admin/block, and from there can be changed manually via block
45	* administration.
46	* Note that if you set a region that isn't available in a given theme, the
47	* block will be registered instead to that theme's default region (the first
48	* item in the _regions array).
49	*
50	* After completing your blocks, do not forget to enable them in the
51	* block admin menu.
52	*
53	* For a detailed usage example, see block_example.module.
54	*/
55	function hook_block_info() {
56	$blocks['exciting'] = array(
57	'info' => t('An exciting block provided by Mymodule.'),
58	'weight' => 0,
59	'status' => 1,
60	'region' => 'sidebar_first',
61	// DRUPAL_CACHE_PER_ROLE will be assumed for block 0.
62	);
63
64	$blocks['amazing'] = array(
65	'info' => t('An amazing block provided by Mymodule.'),
66	'cache' => DRUPAL_CACHE_PER_ROLE \| DRUPAL_CACHE_PER_PAGE,
67	);
68
69	return $blocks;
70	}
71
72	/**
73	* Configuration form for the block.
74	*
75	* @param $delta
76	* Which block to return. This is a descriptive string used to identify
77	* blocks within each module and also within the theme system.
78	* The $delta for each block is defined within the array that your module
79	* returns when the hook_block_info() implementation is called.
80	* @return
81	* Optionally return the configuration form.
82	*
83	* For a detailed usage example, see block_example.module.
84	*/
85	function hook_block_configure($delta = '') {
86	if ($delta == 'exciting') {
87	$form['items'] = array(
88	'#type' => 'select',
89	'#title' => t('Number of items'),
90	'#default_value' => variable_get('mymodule_block_items', 0),
91	'#options' => array('1', '2', '3'),
92	);
93	return $form;
94	}
95	}
96
97	/**
98	* Save the configuration options.
99	*
100	* @param $delta
101	* Which block to save the settings for. This is a descriptive string used
102	* to identify blocks within each module and also within the theme system.
103	* The $delta for each block is defined within the array that your module
104	* returns when the hook_block_info() implementation is called.
105	* @param $edit
106	* The submitted form data from the configuration form.
107	*
108	* For a detailed usage example, see block_example.module.
109	*/
110	function hook_block_save($delta = '', $edit = array()) {
111	if ($delta == 'exciting') {
112	variable_set('mymodule_block_items', $edit['items']);
113	}
114	}
115
116	/**
117	* Process the block when enabled in a region in order to view its contents.
118	*
119	* @param $delta
120	* Which block to return. This is a descriptive string used to identify
121	* blocks within each module and also within the theme system.
122	* The $delta for each block is defined within the array that your module
123	* returns when the hook_block_info() implementation is called.
124	* @return
125	* An array which must define a 'subject' element and a 'content' element
126	* defining the block indexed by $delta.
127	*
128	* The functions mymodule_display_block_exciting and _amazing, as used in the
129	* example, should of course be defined somewhere in your module and return the
130	* content you want to display to your users. If the "content" element is empty,
131	* no block will be displayed even if "subject" is present.
132	*
133	* For a detailed usage example, see block_example.module.
134	*/
135	function hook_block_view($delta = '') {
136	switch ($delta) {
137	case 'exciting':
138	$block = array(
139	'subject' => t('Default title of the exciting block'),
140	'content' => mymodule_display_block_exciting(),
141	);
142	break;
143
144	case 'amazing':
145	$block = array(
146	'subject' => t('Default title of the amazing block'),
147	'content' => mymodule_display_block_amazing(),
148	);
149	break;
150	}
151	return $block;
152	}
153
154	/**
155	* Perform alterations to the content of a block.
156	*
157	* This hook allows you to modify any data returned by hook_block_view().
158	*
159	* Note that instead of hook_block_view_alter(), which is called for all
160	* blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
161	* specific block.
162	*
163	* @param $data
164	* An array of data, as returned from the hook_block_view() implementation of
165	* the module that defined the block:
166	* - subject: The localized title of the block.
167	* - content: Either a string or a renderable array representing the content
168	* of the block. You should check that the content is an array before trying
169	* to modify parts of the renderable structure.
170	* @param $block
171	* The block object, as loaded from the database, having the main properties:
172	* - module: The name of the module that defined the block.
173	* - delta: The identifier for the block within that module, as defined within
174	* hook_block_info().
175	*
176	* @see hook_block_view_alter()
177	* @see hook_block_view()
178	*/
179	function hook_block_view_alter(&$data, $block) {
180	// Remove the contextual links on all blocks that provide them.
181	if (is_array($data['content']) && isset($data['content']['#contextual_links'])) {
182	unset($data['content']['#contextual_links']);
183	}
184	// Add a theme wrapper function defined by the current module to all blocks
185	// provided by the "somemodule" module.
186	if (is_array($data['content']) && $block->module == 'somemodule') {
187	$data['content']['#theme_wrappers'][] = 'mymodule_special_block';
188	}
189	}
190
191	/**
192	* Perform alterations to a specific block.
193	*
194	* Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
195	* specific block, rather than implementing hook_block_view_alter().
196	*
197	* Note that this hook fires before hook_block_view_alter(). Therefore, all
198	* implementations of hook_block_view_MODULE_DELTA_alter() will run before all
199	* implementations of hook_block_view_alter(), regardless of the module order.
200	*
201	* @param $data
202	* An array of data, as returned from the hook_block_view() implementation of
203	* the module that defined the block:
204	* - subject: The localized title of the block.
205	* - content: Either a string or a renderable array representing the content
206	* of the block. You should check that the content is an array before trying
207	* to modify parts of the renderable structure.
208	* @param $block
209	* The block object, as loaded from the database, having the main properties:
210	* - module: The name of the module that defined the block.
211	* - delta: The identifier for the block within that module, as defined within
212	* hook_block_info().
213	*
214	* @see hook_block_view_alter()
215	* @see hook_block_view()
216	*/
217	function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
218	// This code will only run for a specific block. For example, if MODULE_DELTA
219	// in the function definition above is set to "mymodule_somedelta", the code
220	// will only run on the "somedelta" block provided by the "mymodule" module.
221
222	// Change the title of the "somedelta" block provided by the "mymodule"
223	// module.
224	$data['subject'] = t('New title of the block');
225	}
226
227	/**
228	* Act on blocks prior to rendering.
229	*
230	* This hook allows you to add, remove or modify blocks in the block list. The
231	* block list contains the block definitions not the rendered blocks. The blocks
232	* are rendered after the modules have had a chance to manipulate the block
233	* list.
234	* Alternatively you can set $block->content here, which will override the
235	* content of the block and prevent hook_block_view() from running.
236	*
237	* @param $blocks
238	* An array of $blocks, keyed by $bid
239	*
240	* This example shows how to achieve language specific visibility setting for
241	* blocks.
242	*/
243	function hook_block_info_alter(&$blocks) {
244	global $language, $theme_key;
245
246	$result = db_query('SELECT module, delta, language FROM {my_table}');
247	$block_languages = array();
248	foreach ($result as $record) {
249	$block_languages[$record->module][$record->delta][$record->language] = TRUE;
250	}
251
252	foreach ($blocks as $key => $block) {
253	// Any module using this alter should inspect the data before changing it,
254	// to ensure it is what they expect.
255	if ($block->theme != $theme_key \|\| $block->status != 1) {
256	// This block was added by a contrib module, leave it in the list.
257	continue;
258	}
259
260	if (!isset($block_languages[$block->module][$block->delta])) {
261	// No language setting for this block, leave it in the list.
262	continue;
263	}
264
265	if (!isset($block_languages[$block->module][$block->delta][$language->language])) {
266	// This block should not be displayed with the active language, remove
267	// from the list.
268	unset($blocks[$key]);
269	}
270	}
271	}
272
273	/**
274	* @} End of "addtogroup hooks".
275	*/