Projet

Général

Profil

Paste
Télécharger (15,3 ko) Statistiques
| Branche: | Révision:

root / drupal7 / modules / block / block.api.php @ 01f36513

1 85ad3d82 Assos Assos
<?php
2
3
/**
4
 * @file
5
 * Hooks provided by the Block module.
6
 */
7
8
/**
9
 * @addtogroup hooks
10
 * @{
11
 */
12
13
/**
14
 * Define all blocks provided by the module.
15
 *
16
 * This hook declares to Drupal what blocks are provided by your module and can
17
 * optionally specify initial block configuration settings.
18
 *
19
 * In hook_block_info(), each block your module provides is given a unique
20
 * identifier referred to as "delta" (the array key in the return value). Delta
21
 * values only need to be unique within your module, and they are used in the
22
 * following ways:
23
 * - Passed into the other block hooks in your module as an argument to identify
24
 *   the block being configured or viewed.
25
 * - Used to construct the default HTML ID of "block-MODULE-DELTA" applied to
26
 *   each block when it is rendered. This ID may then be used for CSS styling or
27
 *   JavaScript programming.
28
 * - Used to define a theming template suggestion of block__MODULE__DELTA, for
29
 *   advanced theming possibilities.
30
 * - Used by other modules to identify your block in hook_block_info_alter() and
31
 *   other alter hooks.
32
 * The values of delta can be strings or numbers, but because of the uses above
33
 * it is preferable to use descriptive strings whenever possible, and only use a
34
 * numeric identifier if you have to (for instance if your module allows users
35
 * to create several similar blocks that you identify within your module code
36
 * with numeric IDs). The maximum length for delta values is 32 bytes.
37
 *
38
 * @return
39
 *   An associative array whose keys define the delta for each block and whose
40
 *   values contain the block descriptions. Each block description is itself an
41
 *   associative array, with the following key-value pairs:
42
 *   - info: (required) The human-readable administrative name of the block.
43
 *     This is used to identify the block on administration screens, and is not
44
 *     displayed to non-administrative users.
45
 *   - cache: (optional) A bitmask describing what kind of caching is
46
 *     appropriate for the block. Drupal provides the following bitmask
47
 *     constants for defining cache granularity:
48
 *     - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
49
 *       roles the user viewing the page belongs to.
50
 *     - DRUPAL_CACHE_PER_USER: The block can change depending on the user
51
 *       viewing the page. This setting can be resource-consuming for sites with
52
 *       large number of users, and should only be used when
53
 *       DRUPAL_CACHE_PER_ROLE is not sufficient.
54
 *     - DRUPAL_CACHE_PER_PAGE: The block can change depending on the page being
55
 *       viewed.
56
 *     - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every page
57
 *       where it is visible.
58
 *     - DRUPAL_CACHE_CUSTOM: The module implements its own caching system.
59
 *     - DRUPAL_NO_CACHE: The block should not get cached.
60
 *   - properties: (optional) Array of additional metadata to add to the block.
61
 *     Common properties include:
62
 *     - administrative: Boolean that categorizes this block as usable in an
63
 *       administrative context. This might include blocks that help an
64
 *       administrator approve/deny comments, or view recently created user
65
 *       accounts.
66
 *   - weight: (optional) Initial value for the ordering weight of this block.
67
 *     Most modules do not provide an initial value, and any value provided can
68
 *     be modified by a user on the block configuration screen.
69
 *   - status: (optional) Initial value for block enabled status. (1 = enabled,
70
 *     0 = disabled). Most modules do not provide an initial value, and any
71
 *     value provided can be modified by a user on the block configuration
72
 *     screen.
73
 *   - region: (optional) Initial value for theme region within which this
74
 *     block is set. Most modules do not provide an initial value, and any value
75
 *     provided can be modified by a user on the block configuration screen.
76
 *     Note: If you set a region that isn't available in the currently enabled
77
 *     theme, the block will be disabled.
78
 *   - visibility: (optional) Initial value for the visibility flag, which tells
79
 *     how to interpret the 'pages' value. Possible values are:
80
 *     - BLOCK_VISIBILITY_NOTLISTED: Show on all pages except listed pages.
81
 *       'pages' lists the paths where the block should not be shown.
82
 *     - BLOCK_VISIBILITY_LISTED: Show only on listed pages. 'pages' lists the
83
 *       paths where the block should be shown.
84
 *     - BLOCK_VISIBILITY_PHP: Use custom PHP code to determine visibility.
85
 *       'pages' gives the PHP code to use.
86
 *     Most modules do not provide an initial value for 'visibility' or 'pages',
87
 *     and any value provided can be modified by a user on the block
88
 *     configuration screen.
89
 *   - pages: (optional) See 'visibility' above. A string that contains one or
90 4444412d Julien Enselme
 *     more page paths separated by "\n", "\r", or "\r\n" when 'visibility' is
91
 *     set to BLOCK_VISIBILITY_NOTLISTED or BLOCK_VISIBILITY_LISTED (example:
92
 *     "<front>\nnode/1"), or custom PHP code when 'visibility' is set to
93
 *     BLOCK_VISIBILITY_PHP. Paths may use '*' as a wildcard (matching any
94
 *     number of characters); '<front>' designates the site's front page. For
95
 *     BLOCK_VISIBILITY_PHP, the PHP code's return value should be TRUE if the
96
 *     block is to be made visible or FALSE if the block should not be visible.
97 85ad3d82 Assos Assos
 *
98
 * For a detailed usage example, see block_example.module.
99
 *
100
 * @see hook_block_configure()
101
 * @see hook_block_save()
102
 * @see hook_block_view()
103
 * @see hook_block_info_alter()
104
 */
105
function hook_block_info() {
106
  // This example comes from node.module.
107
  $blocks['syndicate'] = array(
108
    'info' => t('Syndicate'),
109
    'cache' => DRUPAL_NO_CACHE
110
  );
111
112
  $blocks['recent'] = array(
113
    'info' => t('Recent content'),
114
    // DRUPAL_CACHE_PER_ROLE will be assumed.
115
  );
116
117
  return $blocks;
118
}
119
120
/**
121
 * Change block definition before saving to the database.
122
 *
123
 * @param $blocks
124
 *   A multidimensional array of blocks keyed by the defining module and delta;
125
 *   the values are blocks returned by hook_block_info(). This hook is fired
126
 *   after the blocks are collected from hook_block_info() and the database,
127
 *   right before saving back to the database.
128
 * @param $theme
129
 *   The theme these blocks belong to.
130
 * @param $code_blocks
131
 *   The blocks as defined in hook_block_info() before being overwritten by the
132
 *   database data.
133
 *
134
 * @see hook_block_info()
135
 */
136
function hook_block_info_alter(&$blocks, $theme, $code_blocks) {
137
  // Disable the login block.
138
  $blocks['user']['login']['status'] = 0;
139
}
140
141
/**
142
 * Define a configuration form for a block.
143
 *
144
 * @param $delta
145
 *   Which block is being configured. This is a unique identifier for the block
146
 *   within the module, defined in hook_block_info().
147
 *
148
 * @return
149
 *   A configuration form, if one is needed for your block beyond the standard
150
 *   elements that the block module provides (block title, visibility, etc.).
151
 *
152
 * For a detailed usage example, see block_example.module.
153
 *
154
 * @see hook_block_info()
155
 * @see hook_block_save()
156
 */
157
function hook_block_configure($delta = '') {
158
  // This example comes from node.module.
159
  $form = array();
160
  if ($delta == 'recent') {
161
    $form['node_recent_block_count'] = array(
162
      '#type' => 'select',
163
      '#title' => t('Number of recent content items to display'),
164
      '#default_value' => variable_get('node_recent_block_count', 10),
165
      '#options' => drupal_map_assoc(array(2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 25, 30)),
166
    );
167
  }
168
  return $form;
169
}
170
171
/**
172
 * Save the configuration options from hook_block_configure().
173
 *
174
 * This hook allows you to save the block-specific configuration settings
175
 * defined within your hook_block_configure().
176
 *
177
 * @param $delta
178
 *   Which block is being configured. This is a unique identifier for the block
179
 *   within the module, defined in hook_block_info().
180
 * @param $edit
181
 *   The submitted form data from the configuration form.
182
 *
183
 * For a detailed usage example, see block_example.module.
184
 *
185
 * @see hook_block_configure()
186
 * @see hook_block_info()
187
 */
188
function hook_block_save($delta = '', $edit = array()) {
189
  // This example comes from node.module.
190
  if ($delta == 'recent') {
191
    variable_set('node_recent_block_count', $edit['node_recent_block_count']);
192
  }
193
}
194
195
/**
196
 * Return a rendered or renderable view of a block.
197
 *
198
 * @param $delta
199
 *   Which block to render. This is a unique identifier for the block
200
 *   within the module, defined in hook_block_info().
201
 *
202
 * @return
203
 *   Either an empty array so the block will not be shown or an array containing
204
 *   the following elements:
205
 *   - subject: The default localized title of the block. If the block does not
206
 *     have a default title, this should be set to NULL.
207
 *   - content: The content of the block's body. This may be a renderable array
208
 *     (preferable) or a string containing rendered HTML content. If the content
209
 *     is empty the block will not be shown.
210
 *
211
 * For a detailed usage example, see block_example.module.
212
 *
213
 * @see hook_block_info()
214
 * @see hook_block_view_alter()
215
 * @see hook_block_view_MODULE_DELTA_alter()
216
 */
217
function hook_block_view($delta = '') {
218
  // This example is adapted from node.module.
219
  $block = array();
220
221
  switch ($delta) {
222
    case 'syndicate':
223
      $block['subject'] = t('Syndicate');
224
      $block['content'] = array(
225
        '#theme' => 'feed_icon',
226
        '#url' => 'rss.xml',
227
        '#title' => t('Syndicate'),
228
      );
229
      break;
230
231
    case 'recent':
232
      if (user_access('access content')) {
233
        $block['subject'] = t('Recent content');
234
        if ($nodes = node_get_recent(variable_get('node_recent_block_count', 10))) {
235
          $block['content'] = array(
236
            '#theme' => 'node_recent_block',
237
            '#nodes' => $nodes,
238
          );
239
        } else {
240
          $block['content'] = t('No content available.');
241
        }
242
      }
243
      break;
244
  }
245
  return $block;
246
}
247
248
/**
249
 * Perform alterations to the content of a block.
250
 *
251
 * This hook allows you to modify any data returned by hook_block_view().
252
 *
253
 * Note that instead of hook_block_view_alter(), which is called for all
254
 * blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
255
 * specific block.
256
 *
257
 * @param $data
258
 *   The data as returned from the hook_block_view() implementation of the
259
 *   module that defined the block. This could be an empty array or NULL value
260
 *   (if the block is empty) or an array containing:
261
 *   - subject: The default localized title of the block.
262
 *   - content: Either a string or a renderable array representing the content
263
 *     of the block. You should check that the content is an array before trying
264
 *     to modify parts of the renderable structure.
265
 * @param $block
266
 *   The block object, as loaded from the database, having the main properties:
267
 *   - module: The name of the module that defined the block.
268
 *   - delta: The unique identifier for the block within that module, as defined
269
 *     in hook_block_info().
270
 *
271
 * @see hook_block_view_MODULE_DELTA_alter()
272
 * @see hook_block_view()
273
 */
274
function hook_block_view_alter(&$data, $block) {
275
  // Remove the contextual links on all blocks that provide them.
276
  if (is_array($data['content']) && isset($data['content']['#contextual_links'])) {
277
    unset($data['content']['#contextual_links']);
278
  }
279
  // Add a theme wrapper function defined by the current module to all blocks
280
  // provided by the "somemodule" module.
281
  if (is_array($data['content']) && $block->module == 'somemodule') {
282
    $data['content']['#theme_wrappers'][] = 'mymodule_special_block';
283
  }
284
}
285
286
/**
287
 * Perform alterations to a specific block.
288
 *
289
 * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
290
 * specific block, rather than implementing hook_block_view_alter().
291
 *
292
 * @param $data
293
 *   The data as returned from the hook_block_view() implementation of the
294
 *   module that defined the block. This could be an empty array or NULL value
295
 *   (if the block is empty) or an array containing:
296
 *   - subject: The localized title of the block.
297
 *   - content: Either a string or a renderable array representing the content
298
 *     of the block. You should check that the content is an array before trying
299
 *     to modify parts of the renderable structure.
300
 * @param $block
301
 *   The block object, as loaded from the database, having the main properties:
302
 *   - module: The name of the module that defined the block.
303
 *   - delta: The unique identifier for the block within that module, as defined
304
 *     in hook_block_info().
305
 *
306
 * @see hook_block_view_alter()
307
 * @see hook_block_view()
308
 */
309
function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
310
  // This code will only run for a specific block. For example, if MODULE_DELTA
311
  // in the function definition above is set to "mymodule_somedelta", the code
312
  // will only run on the "somedelta" block provided by the "mymodule" module.
313
314
  // Change the title of the "somedelta" block provided by the "mymodule"
315
  // module.
316
  $data['subject'] = t('New title of the block');
317
}
318
319
/**
320
 * Act on blocks prior to rendering.
321
 *
322
 * This hook allows you to add, remove or modify blocks in the block list. The
323
 * block list contains the block definitions, not the rendered blocks. The
324
 * blocks are rendered after the modules have had a chance to manipulate the
325
 * block list.
326
 *
327
 * You can also set $block->content here, which will override the content of the
328
 * block and prevent hook_block_view() from running.
329
 *
330
 * @param $blocks
331
 *   An array of $blocks, keyed by the block ID.
332
 */
333
function hook_block_list_alter(&$blocks) {
334
  global $language, $theme_key;
335
336
  // This example shows how to achieve language specific visibility setting for
337
  // blocks.
338
339
  $result = db_query('SELECT module, delta, language FROM {my_table}');
340
  $block_languages = array();
341
  foreach ($result as $record) {
342
    $block_languages[$record->module][$record->delta][$record->language] = TRUE;
343
  }
344
345
  foreach ($blocks as $key => $block) {
346
    // Any module using this alter should inspect the data before changing it,
347
    // to ensure it is what they expect.
348
    if (!isset($block->theme) || !isset($block->status) || $block->theme != $theme_key || $block->status != 1) {
349
      // This block was added by a contrib module, leave it in the list.
350
      continue;
351
    }
352
353
    if (!isset($block_languages[$block->module][$block->delta])) {
354
      // No language setting for this block, leave it in the list.
355
      continue;
356
    }
357
358
    if (!isset($block_languages[$block->module][$block->delta][$language->language])) {
359
      // This block should not be displayed with the active language, remove
360
      // from the list.
361
      unset($blocks[$key]);
362
    }
363
  }
364
}
365
366 582db59d Assos Assos
/**
367
 * Act on block cache ID (cid) parts before the cid is generated.
368
 *
369
 * This hook allows you to add, remove or modify the custom keys used to
370
 * generate a block cache ID (by default, these keys are set to the block
371
 * module and delta). These keys will be combined with the standard ones
372
 * provided by drupal_render_cid_parts() to generate the final block cache ID.
373
 *
374
 * To change the cache granularity used by drupal_render_cid_parts(), this hook
375
 * cannot be used; instead, set the 'cache' key in the block's definition in
376
 * hook_block_info().
377
 *
378
 * @params $cid_parts
379
 *   An array of elements used to build the cid.
380
 * @param $block
381
 *   The block object being acted on.
382
 *
383
 * @see _block_get_cache_id()
384
 */
385
function hook_block_cid_parts_alter(&$cid_parts, $block) {
386
  global $user;
387
  // This example shows how to cache a block based on the user's timezone.
388
  $cid_parts[] = $user->timezone;
389
}
390
391 85ad3d82 Assos Assos
/**
392
 * @} End of "addtogroup hooks".
393
 */