block.module 17.4 KB
Newer Older
Dries's avatar
   
Dries committed
1
<?php
2
// $Id$
Dries's avatar
   
Dries committed
3

Dries's avatar
   
Dries committed
4
5
6
7
8
/**
 * @file
 * Controls the boxes that are displayed around the main content.
 */

Dries's avatar
   
Dries committed
9
10
11
12
/**
 * Implementation of hook_help().
 */
function block_help($section) {
Dries's avatar
   
Dries committed
13
  switch ($section) {
Dries's avatar
   
Dries committed
14
    case 'admin/help#block':
15
      return t('
16
<p>Blocks are the boxes visible in the sidebar(s) of your web site. These are usually generated automatically by modules (e.g. recent forum topics), but you can also create your own blocks.</p>
17
18
19
20
21
22
23
24
25
26
27
28
29
<p>The sidebar each block appears in depends on both which theme you are using (some are left-only, some right, some both), and on the settings in block management.</p>
<p>The block management screen lets you specify the vertical sort-order of the blocks within a sidebar. You do this by assigning a weight to each block. Lighter blocks (smaller weight) "float up" towards the top of the sidebar. Heavier ones "sink down" towards the bottom of it.</p>
<p>A block\'s visibility depends on:</p>
<ul>
<li>Its enabled checkbox. Disabled blocks are never shown.</li>
<li>Its throttle checkbox. Throttled blocks are hidden during high server loads.</li>
<li>Its path options. Blocks can be configured to only show/hide on certain pages</li>.
<li>User settings. You can choose to let your users decide whether to show/hide certain blocks.</li>
<li>Its function. Dynamic blocks (such as those defined by modules) may be empty on certain pages and will not be shown.</li>
</ul>

<h3>Administrator defined blocks</h3>
<p>An administrator defined block contains content supplied by you (as opposed to being generated automatically by a module). Each admin-defined block consists of a title, a description, and a body which can be as long as you wish. The Drupal engine will render the content of the block.</p>');
Dries's avatar
   
Dries committed
30
    case 'admin/modules#description':
Dries's avatar
   
Dries committed
31
      return t('Controls the boxes that are displayed around the main content.');
Dries's avatar
   
Dries committed
32
    case 'admin/block':
33
34
35
      return t("
<p>Blocks are the boxes in the left and right side bars of the web site. They are made available by modules or created manually.</p>
<p>Only enabled blocks are shown. You can position the blocks by deciding which side of the page they will show up on (region) and in which order they appear (weight).</p>
36
<p>If you want certain blocks to disable themselves temporarily during high server loads, check the 'Throttle' box. You can configure the auto-throttle on the <a href=\"%throttle\">throttle configuration page</a> after having enabled the throttle module.
37
", array('%throttle' => url('admin/settings/throttle')));
Dries's avatar
   
Dries committed
38
    case 'admin/block/add':
39
      return t("Here you can create a new block. Once you have created this block you must make it active and give it a place on the page using <a href=\"%overview\">blocks</a>. The title is used when displaying the block. The description is used in the \"block\" column on the <a href=\"%overview\">blocks</a> page.", array('%overview' => url('admin/block')));
Dries's avatar
   
Dries committed
40
  }
Dries's avatar
   
Dries committed
41
42
}

Dries's avatar
   
Dries committed
43
44
45
/**
 * Implementation of hook_perm().
 */
Dries's avatar
   
Dries committed
46
function block_perm() {
Dries's avatar
   
Dries committed
47
  return array('administer blocks');
Dries's avatar
   
Dries committed
48
49
}

Dries's avatar
   
Dries committed
50
/**
Dries's avatar
   
Dries committed
51
 * Implementation of hook_menu().
Dries's avatar
   
Dries committed
52
 */
Dries's avatar
   
Dries committed
53
function block_menu($may_cache) {
Dries's avatar
   
Dries committed
54
  $items = array();
Dries's avatar
   
Dries committed
55
56
57
58
59
60
61

  if ($may_cache) {
    $items[] = array('path' => 'admin/block', 'title' => t('blocks'),
      'access' => user_access('administer blocks'),
      'callback' => 'block_admin');
    $items[] = array('path' => 'admin/block/list', 'title' => t('list'),
      'type' => MENU_DEFAULT_LOCAL_TASK, 'weight' => -10);
62
    $items[] = array('path' => 'admin/block/configure', 'title' => t('configure block'),
Dries's avatar
   
Dries committed
63
      'access' => user_access('administer blocks'),
64
65
66
67
68
      'callback' => 'block_admin_configure',
      'type' => MENU_CALLBACK);
    $items[] = array('path' => 'admin/block/delete', 'title' => t('delete block'),
      'access' => user_access('administer blocks'),
      'callback' => 'block_box_delete',
Dries's avatar
   
Dries committed
69
      'type' => MENU_CALLBACK);
Dries's avatar
   
Dries committed
70
    $items[] = array('path' => 'admin/block/add', 'title' => t('add block'),
Dries's avatar
   
Dries committed
71
      'access' => user_access('administer blocks'),
72
      'callback' => 'block_box_add',
Dries's avatar
   
Dries committed
73
74
75
      'type' => MENU_LOCAL_TASK);
  }

Dries's avatar
   
Dries committed
76
  return $items;
Dries's avatar
   
Dries committed
77
78
}

Dries's avatar
   
Dries committed
79
80
81
82
83
/**
 * Implementation of hook_block().
 *
 * Generates the administrator-defined blocks for display.
 */
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
function block_block($op = 'list', $delta = 0, $edit = array()) {
  switch ($op) {
    case 'list':
      $result = db_query('SELECT bid, title, info FROM {boxes} ORDER BY title');
      while ($block = db_fetch_object($result)) {
        $blocks[$block->bid]['info'] = $block->info;
      }
      return $blocks;

    case 'configure':
      $box = block_box_get($delta);
      if (filter_access($box['format'])) {
        return block_box_form($box);
      }
      break;

    case 'save':
      block_box_save($edit, $delta);
      break;

    case 'view':
      $block = db_fetch_object(db_query('SELECT * FROM {boxes} WHERE bid = %d', $delta));
      $data['subject'] = $block->title;
      $data['content'] = check_output($block->body, $block->format);
      return $data;
109
110
111
  }
}

Dries's avatar
   
Dries committed
112
function block_admin_save($edit) {
Dries's avatar
   
Dries committed
113
114
  foreach ($edit as $module => $blocks) {
    foreach ($blocks as $delta => $block) {
115
116
      db_query("UPDATE {blocks} SET region = %d, status = %d, weight = %d, throttle = %d WHERE module = '%s' AND delta = '%s'",
                $block['region'], $block['status'], $block['weight'], $block['throttle'], $module, $delta);
Dries's avatar
   
Dries committed
117
    }
Dries's avatar
   
Dries committed
118
  }
Dries's avatar
   
Dries committed
119

120
  return t('The block settings have been updated.');
Dries's avatar
   
Dries committed
121
122
}

Dries's avatar
   
Dries committed
123
/**
Dries's avatar
   
Dries committed
124
 * Update the 'blocks' DB table with the blocks currently exported by modules.
Dries's avatar
   
Dries committed
125
 *
Dries's avatar
   
Dries committed
126
127
128
 * @param $order_by php <a
 *   href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a>
 *   style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
129
 *
Dries's avatar
   
Dries committed
130
131
 * @return
 *   Blocks currently exported by modules, sorted by $order_by.
Dries's avatar
   
Dries committed
132
 */
Dries's avatar
   
Dries committed
133
134
function _block_rehash($order_by = array('weight')) {
  $result = db_query('SELECT * FROM {blocks} ');
Dries's avatar
   
Dries committed
135
136
137
138
  while ($old_block = db_fetch_object($result)) {
    $old_blocks[$old_block->module][$old_block->delta] = $old_block;
  }

Dries's avatar
   
Dries committed
139
  db_query('DELETE FROM {blocks} ');
Dries's avatar
   
Dries committed
140
141

  foreach (module_list() as $module) {
Dries's avatar
   
Dries committed
142
    $module_blocks = module_invoke($module, 'block', 'list');
Dries's avatar
   
Dries committed
143
144
    if ($module_blocks) {
      foreach ($module_blocks as $delta => $block) {
Dries's avatar
   
Dries committed
145
146
        $block['module'] = $module;
        $block['delta']  = $delta;
Dries's avatar
   
Dries committed
147
        if ($old_blocks[$module][$delta]) {
Dries's avatar
   
Dries committed
148
149
150
          $block['status'] = $old_blocks[$module][$delta]->status;
          $block['weight'] = $old_blocks[$module][$delta]->weight;
          $block['region'] = $old_blocks[$module][$delta]->region;
151
152
          $block['visibility'] = $old_blocks[$module][$delta]->visibility;
          $block['pages'] = $old_blocks[$module][$delta]->pages;
Dries's avatar
   
Dries committed
153
154
          $block['custom'] = $old_blocks[$module][$delta]->custom;
          $block['throttle'] = $old_blocks[$module][$delta]->throttle;
Dries's avatar
   
Dries committed
155
156
        }
        else {
Dries's avatar
   
Dries committed
157
          $block['status'] = $block['weight'] = $block['region'] = $block['custom'] = 0;
158
          $block['pages']   = '';
Dries's avatar
   
Dries committed
159
160
161
        }

        // reinsert blocks into table
162
163
        db_query("INSERT INTO {blocks} (module, delta, status, weight, region, visibility, pages, custom, throttle) VALUES ('%s', '%s', %d, %d, %d, %d, '%s', %d, %d)",
                  $block['module'], $block['delta'], $block['status'], $block['weight'], $block['region'], $block['visibility'], $block['pages'], $block['custom'], $block['throttle']);
Dries's avatar
   
Dries committed
164
165

        $blocks[] = $block;
Dries's avatar
   
Dries committed
166

Dries's avatar
   
Dries committed
167
168
        // build array to sort on
        $order[$order_by[0]][] = $block[$order_by[0]];
Dries's avatar
   
Dries committed
169
170
171
172
      }
    }
  }

Dries's avatar
   
Dries committed
173
174
175
  // sort
  array_multisort($order[$order_by[0]], $order_by[1] ? $order_by[1] : SORT_ASC, $order_by[2] ? $order_by[2] : SORT_REGULAR, $blocks);

Dries's avatar
   
Dries committed
176
177
  return $blocks;
}
Dries's avatar
   
Dries committed
178

Dries's avatar
   
Dries committed
179
180
181
/**
 * Prepare the main block administration form.
 */
Dries's avatar
   
Dries committed
182
function block_admin_display() {
Dries's avatar
   
Dries committed
183
  $blocks = _block_rehash();
Dries's avatar
   
Dries committed
184

Dries's avatar
   
Dries committed
185
186
187
188
189
190
  $header = array(t('Block'), t('Enabled'), t('Weight'), t('Region'));
  if (module_exist('throttle')) {
    $header[] = t('Throttle');
  }
  $header[] = array('data' => t('Operations'), 'colspan' => 2);

Dries's avatar
   
Dries committed
191

Dries's avatar
   
Dries committed
192
  foreach ($blocks as $block) {
193
194
    if ($block['module'] == 'block') {
      $operation = l(t('delete'), 'admin/block/delete/'. $block['delta']);
195
    }
Dries's avatar
   
Dries committed
196
    else {
197
      $operation = '';
Dries's avatar
   
Dries committed
198
    }
Dries's avatar
   
Dries committed
199

Dries's avatar
   
Dries committed
200
201
202
203
204
205
206
207
    $row = array($block['info'], array('data' => form_checkbox(NULL, $block['module'] .']['. $block['delta'] .'][status', 1, $block['status']), 'align' => 'center'), form_weight(NULL, $block['module'] .']['. $block['delta'] .'][weight', $block['weight']), form_radios(NULL, $block['module'] .']['. $block['delta'] .'][region', $block['region'], array(t('left'), t('right'))));

    $row = array($block['info'], array('data' => form_checkbox(NULL, $block['module'] .']['. $block['delta'] .'][status', 1, $block['status']), 'align' => 'center'), form_weight(NULL, $block['module'] .']['. $block['delta'] .'][weight', $block['weight']), form_radios(NULL, $block['module'] .']['. $block['delta'] .'][region', $block['region'], array(t('left'), t('right'))));
    if (module_exist('throttle')) {
      $row[] = array('data' => form_checkbox(NULL, $block['module'] .']['. $block['delta'] .'][throttle', 1, $block['throttle']), 'align' => 'center');
    }
    $row[] = array('data' => l(t('configure'), 'admin/block/configure/'. $block['module'] .'/'. $block['delta']), $operation);
    $rows[] = $row;
Dries's avatar
   
Dries committed
208
  }
Dries's avatar
   
Dries committed
209

Dries's avatar
   
Dries committed
210
211
  $output = theme('table', $header, $rows);
  $output .= form_submit(t('Save blocks'));
Dries's avatar
   
Dries committed
212

Dries's avatar
   
Dries committed
213
  return form($output, 'post', url('admin/block'));
Dries's avatar
   
Dries committed
214
215
}

216
function block_box_get($bid) {
Dries's avatar
   
Dries committed
217
218
219
220
  return db_fetch_array(db_query('SELECT * FROM {boxes} WHERE bid = %d', $bid));
}

/**
221
 * Menu callback; displays the block configuration form.
Dries's avatar
   
Dries committed
222
 */
223
function block_admin_configure($module = NULL, $delta = 0) {
Dries's avatar
   
Dries committed
224
225
226
  $edit = $_POST['edit'];
  $op = $_POST['op'];

227
228
  switch ($op) {
    case t('Save block'):
229
230
231
      db_query("UPDATE {blocks} SET visibility = %d, pages = '%s', custom = %d WHERE module = '%s' AND delta = '%s'", $edit['visibility'], $edit['pages'], $edit['custom'], $module, $delta);
      module_invoke($module, 'block', 'save', $delta, $edit);
      drupal_set_message('The block configuration has been saved.');
232
233
234
      cache_clear_all();
      drupal_goto('admin/block');

235
236
237
238
239
240
241
242
243
244
245
246
247
248
    default:
      // Always evaluates to TRUE, but a validation step may be added later.
      if (!$edit) {
        $edit = db_fetch_array(db_query("SELECT pages, visibility, custom FROM {blocks} WHERE module = '%s' AND delta = '%s'", $module, $delta));
      }

      // Module-specific block configurations.
      if ($settings = module_invoke($module, 'block', 'configure', $delta)) {
        $form = form_group(t('Block-specific settings'), $settings);
      }

      // Get the block subject for the page title.
      $info = module_invoke($module, 'block', 'list');
      drupal_set_title(t("'%name' block", array('%name' => $info[$delta]['info'])));
249

250
251
252
253
      // Standard block configurations.
      $group = form_radios(t('Show on specific pages'), 'visibility', $edit['visibility'], array(t('Show on every page except the listed pages.'), t('Show on only the listed pages.')));
      $group .= form_textarea(t('Pages'), 'pages', $edit['pages'], 40, 5, t("Enter one page per line as Drupal paths. The '*' character is a wildcard. Example paths are '<em>blog</em>' for the blog page and '<em>blog/*</em>' for every personal blog. '<em>&lt;front&gt;</em>' is the front page. "));

254
      $group .= form_radios(t('Custom visibility settings'), 'custom', $edit['custom'], array(t('Users cannot control whether or not they see this block.'), t('Show this block by default, but let individual users hide it.'), t('Hide this block by default but let individual users show it.')), t('Allow individual users to customize the visibility of this block in their account settings.'));
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293

      $form .= form_group(t('Visibility settings'), $group);

      $form .= form_submit(t('Save block'));

      print theme('page', form($form));
  }
}

/**
 * Menu callback; displays the block creation form.
 */
function block_box_add() {
  $edit = $_POST['edit'];
  $op = $_POST['op'];

  switch ($op) {
    case t('Save block'):
      block_box_save($edit);
      drupal_set_message(t('The new block has been added.'));
      drupal_goto('admin/block');

    default:
      $form = block_box_form();
      $form .= form_submit(t('Save block'));
      $output .= form($form);
  }

  print theme('page', $output);
}

/**
 * Menu callback; confirm and delete custom blocks.
 */
function block_box_delete($bid = 0) {
  $op = $_POST['op'];
  $box = block_box_get($bid);

  switch ($op) {
294
295
    case t('Delete'):
      db_query('DELETE FROM {boxes} WHERE bid = %d', $bid);
296
      drupal_set_message(t('The block %name has been deleted.', array('%name' => '<em>'. $box['info'] .'</em>')));
297
298
299
300
      cache_clear_all();
      drupal_goto('admin/block');

    default:
301
302
303
      $form = '<p>'. t('Are you sure you want to delete the block %name?', array('%name' => '<em>'. $box['info'] .'</em>')) ."</p>\n";
      $form .= form_submit(t('Delete'));
      $output = form($form);
Dries's avatar
   
Dries committed
304
305
306
  }

  print theme('page', $output);
307
308
309
}

function block_box_form($edit = array()) {
310
311
312
313
  $output = form_textfield(t('Block title'), 'title', $edit['title'], 50, 64, t('The title of the block as shown to the user.'));
  $output .= filter_form('format', $edit['format']);
  $output .= form_textarea(t('Block body'), 'body', $edit['body'], 70, 10, t('The content of the block as shown to the user.'));
  $output .= form_textfield(t('Block description'), 'info', $edit['info'], 50, 64, t('A brief description of your block.  Used on the <a href="%overview">block overview page</a>.', array('%overview' => url('admin/block'))));
314

315
  return $output;
316
317
}

318
function block_box_save($edit, $delta = NULL) {
319
320
  if (!filter_access($edit['format'])) {
    $edit['format'] = FILTER_FORMAT_DEFAULT;
Dries's avatar
   
Dries committed
321
322
  }

323
324
  if (isset($delta)) {
    db_query("UPDATE {boxes} SET title = '%s', body = '%s', info = '%s', format = %d WHERE bid = %d", $edit['title'], $edit['body'], $edit['info'], $edit['format'], $delta);
325
326
  }
  else {
327
    db_query("INSERT INTO {boxes} (title, body, info, format) VALUES  ('%s', '%s', '%s', %d)", $edit['title'], $edit['body'], $edit['info'], $edit['format']);
328
329
330
  }
}

Dries's avatar
   
Dries committed
331
/**
Dries's avatar
Dries committed
332
 * Menu callback; displays the block overview page.
Dries's avatar
   
Dries committed
333
 */
Dries's avatar
   
Dries committed
334
function block_admin() {
Dries's avatar
   
Dries committed
335
336
  $edit = $_POST['edit'];
  $op = $_POST['op'];
Dries's avatar
   
Dries committed
337

Dries's avatar
   
Dries committed
338
339
340
  if ($op == t('Save blocks')) {
    drupal_set_message(block_admin_save($edit));
    cache_clear_all();
341
    drupal_goto($_GET['q']);
Dries's avatar
   
Dries committed
342
  }
Dries's avatar
   
Dries committed
343
  print theme('page', block_admin_display());
Dries's avatar
   
Dries committed
344
}
Dries's avatar
   
Dries committed
345

Dries's avatar
   
Dries committed
346
347
348
349
350
351
/**
 * Implementation of hook_user().
 *
 * Allow users to decide which custom blocks to display when they visit
 * the site.
 */
352
function block_user($type, $edit, &$user, $category = NULL) {
353
  switch ($type) {
354
    case 'form':
355
      if ($category == 'account') {
356
        $result = db_query('SELECT * FROM {blocks} WHERE status = 1 AND custom != 0 ORDER BY weight, module, delta');
357
358
359
360

        while ($block = db_fetch_object($result)) {
          $data = module_invoke($block->module, 'block', 'list');
          if ($data[$block->delta]['info']) {
361
            $form .= form_checkbox($data[$block->delta]['info'], 'block]['. $block->module .']['. $block->delta, 1, isset($user->block[$block->module][$block->delta]) ? $user->block[$block->module][$block->delta] : ($block->custom == 1));
362
          }
Kjartan's avatar
Kjartan committed
363
364
        }

365
366
367
        if (isset($form)) {
          return array(array('title' => t('Block configuration'), 'data' => $form, 'weight' => 2));
        }
368
      }
Dries's avatar
   
Dries committed
369
370

      break;
Dries's avatar
   
Dries committed
371
372
373
    case 'validate':
      if (!$edit['block']) {
        $edit['block'] = array();
374
375
      }
      return $edit;
376
377
378
  }
}

379
380
381
/**
 * Return blocks available for current $user at $region.
 *
Dries's avatar
   
Dries committed
382
 * @param $region main|left|right
383
 *
Dries's avatar
   
Dries committed
384
 * @return array of block objects, indexed with <i>module</i>_<i>delta</i>
385
 *
Dries's avatar
   
Dries committed
386
 * @see <a href="http://drupal.org/node/1042" target="_top">[feature]
387
 *   Generic template design difficult w/o block region "look-ahead"</a>
Dries's avatar
   
Dries committed
388
 * @todo add a proper primary key (bid) to the blocks table so we don't have
389
390
391
392
 *   to mess around with this <i>module</i>_<i>delta</i> construct. currently,
 *   "blocks" has no primary key defined (bad)!
 */
function block_list($region) {
393
  global $user;
394
395
396
397
  static $blocks = array();

  if (!isset($blocks[$region])) {
    $blocks[$region] = array();
398
    $result = db_query('SELECT * FROM {blocks} WHERE status = 1 '. ($region != 'all' ? 'AND region = %d ' : '') .'ORDER BY weight, module', $region == 'left' ? 0 : 1);
399
400

    while ($result && ($block = db_fetch_array($result))) {
401
402
403
404
405
406
407
408
409
410
411
      // Use the user's block visibility setting, if necessary
      if ($block['custom'] != 0) {
        if ($user->uid && isset($user->block[$block['module']][$block['delta']])) {
          $enabled = $user->block[$block['module']][$block['delta']];
        }
        else {
          $enabled = ($block['custom'] == 1);
        }
      }
      else {
        $enabled = TRUE;
412
      }
413
414

      // Match path if necessary
415
      if ($block['pages']) {
416
        $path = drupal_get_path_alias($_GET['q']);
417
        $regexp = '/^('. preg_replace(array('/(\r\n?|\n)/', '/\\\\\*/', '/(^|\|)\\\\<front\\\\>($|\|)/'), array('|', '.*', '\1\2'), preg_quote($block['pages'], '/')) .')$/';
418
        $matched = !($block['visibility'] xor preg_match($regexp, $path));
419
420
      }
      else {
421
        $matched = TRUE;
422
423
      }

424
425
426
      if ($enabled && $matched) {
        // Check the current throttle status and see if block should be displayed
        // based on server load.
427
        if (!($block['throttle'] && (module_invoke('throttle', 'status') > 0))) {
428
          $array = module_invoke($block['module'], 'block', 'view', $block['delta']);
Dries's avatar
   
Dries committed
429
          if (is_array($array)) {
430
431
            $block = array_merge($block, $array);
          }
Dries's avatar
   
Dries committed
432
        }
Dries's avatar
   
Dries committed
433
        if (isset($block['content']) && $block['content']) {
434
435
436
437
438
439
440
441
          $blocks[$region]["$block[module]_$block[delta]"] = (object) $block;
        }
      }
    }
  }
  return $blocks[$region];
}

442
?>