Introduction

Blocktable allows you to embed all the blocks in a region into an HTML table. You create the table markup and place the blocks into it in any arrangement you want. You can use any table markup, such as colspan and rowspan. You can apply any styling to the table and table cells that you want. The block contents and styling are not changed.

This can be very useful for achieving certain layout requirements, such as arranging blocks in a multi-column format.

Terminology

In this Handbook page, 'Blocktable', with an uppercase 'B', refers to the Blocktable module, and 'blocktable', with a lowercase 'b' refers to an individual table defined for a particular region.

Requirements

None.

Installation

Install as usual, see Installing contributed modules for further information.

Configuration

  1. Check the region that you want to use a blocktable in. On the Blocks page, Administer -> Site Building -> Blocks, make sure the correct blocks are in the region, and in the same order that they will appear in in the table markup.
  2. Configure user permissions in Administer >> User management >> Permissions >> blocktable module:
    administer blocktables
    Users in roles with the "administer blocktables" permission can create or edit blocktables.
    use PHP for blocktable visibility
    Users in roles with the "use PHP for blocktable visibility" permission can provide php to be used to determine which pages a blocktable is applied to. This closely follows the logic in block.module.
  3. Edit the block template for the region which is getting the blocktable. For example, if you want to put a blocktable in the content region, edit block-content.tpl.php. If this file does not exist in your theme, copy block.tpl.html to block-content.tpl.html. It is possible to use block.tpl.php, but it will hurt performance somewhat.

    Add a call to Blocktable near the top of the block template file. This must be placed right after the <?php $Id ... > section and before any HTML is generated. Usually a <div> is the first HTML. Here is the line to add: 

             <?php if (function_exists(blocktable_make_table)) {print blocktable_make_table($block, 'start');} ?>

    Add another, slightly different, call to Blocktable at the bottom, after all HTML has been generated. Usually a </div> or comment is the last HTML. Here is the line to add:

             <?php if (function_exists(blocktable_make_table)) {print blocktable_make_table($block, 'end');} ?>
  4. To configure a blocktable, go to Administer -> Site Building -> Blocktable. Configuration is a two step process.
    1. Choose a region from the list. Only regions that are in the current default theme and contain blocks are shown. Each region has a brief description:
      Create new blocktable
      Means there is no blocktable defined for this region.
      Edit existing blocktable
      Means there is a definition that you can edit.
      Edit existing blocktable - Currently invalid
      Means that the existing blocktable definition is invalid because the blocks in the definition no longer match the blocks in the region. This is checked everytime a page is built, and Blocktable will not add table markup to a region if the definition is invalid. You must edit the blocktable definition so that the markup matches the blocks in the region.
    2. Enter the table markup you want to use for the region. See below for details on table markup. You can also specify the pages where the blocktable should appear. This uses the same system as the blocks themselves. You probably want to set this up similarly to the blocks which are in the region.

Table Markup

You must supply your own table markup. Blocktable table markup consists of HTML table tags, like <table>, and block IDs wrapped in colons, like :37:. The configuration page includes a list of the block IDs in the required order. The block IDs are placed between, not within, tags, at the place where the block should go in the completed page.

Example: Here is a table with 2 rows and 3 columns. 6 blocks (with block IDs 35, 33, 37, 23, 40, and 38) are assigned to the cells. Some cells get 1 block, some get more than 1, some get none. Each block must be assigned to exactly one cell.

   <table id="my_id" class="my_class">
      <tr>
         <td>:35::33:</td>
         <td>:37:</td>
         <td>:23:</td>
      </tr>
      <tr>
         <td>:40:</td>
         <td></td>
         <td>:38:</td>
      </tr>
   </table>

There are no restrictions on the table markup. Colspan, rowspan, classes, styling, etc., are permitted. Markup is passed through to the page with no change.

Whitespace (spaces, newlines, etc.) is OK, and is usually passed through to the processed page.

Blocks must appear in the table markup in the weighted order they are listed in. If you want a different order, go back to the Blocks page and change the order there.

If you change the order of the blocks, or add blocks to the region, or remove blocks from the region, you must update the blocktable for that region. Otherwise Blocktable will not add any table markup. No warning is issued when this happens.

It may happen that a block that is included in the blocktable definition is not included on some page, due to block rules, roles & permissions, etc. This is not considered an error, and the table is built without that block's contents. However, if the missing block is the last one expected, the closing table markup will not be included, which will probably break the page. If this problem occurs, you can fix it with a dummy block. Here is one way to create a dummy block:

  1. On the Blocks page, create a block that consists of an HTML comment, such as
    <!-- Dummy block for Blocktable -->
  2. Assign the block to the region with the blocktable.
  3. Make sure it always visible whenever the blocktable is visible.
  4. Make sure it is last in the list (has the heaviest weight).

You can define blocktables for any region that contains blocks.

Styling

Table and Cell Styling

Although there are no restrictions on the table markup, note that the blocks in the table cells are wrapped within several layers of divs which have their own styling. This can make styling at the table cell level complicated.

Block Styling

No change is made to the blocks besides wrapping them with the table markup. However, styling for the blocks, especially anything involving floats and positioning, may be affected since the blocks are now enclosed in table cells.

Disabling

There is more than one way to temporarily disable a blocktable. Any of these will do:

  • Remove both calls to blocktable_make_table in block-<region>.tpl.html. This prevents all Blocktable activity during page generation.
  • Set the path visibility setting so that the blocktable is never visible.
  • Leave the table markup blank in the blocktable configuration.
  • Delete the blocktable_definition entry in the variable table. This will disable ALL blocktables, and if you want to re-implement the blocktables, you will have to repeat the configuration process.

Uninstalling

Recommended steps:

  1. Remove both calls (top and bottom) to blocktable_make_table in block-<region>.tpl.html.
  2. Disable the Blocktable module.
  3. Uninstall the Blocktable module. This deletes the blocktable_definition entry in the variable table.

Limitations

Blocktable only works on blocks. Depending on the theme, some regions, like the header, may have components such as logos, slogans, etc., that are not blocks. Blocktable won't work properly in those cases. You could address this problem by modifying the theme to remove the non-block components, and then add them back in within blocks. However, this is too theme-dependent and complex to make any recommendations here.

If you add, remove, or reorder blocks in the region using the Blocks page, you must make corresponding changes to the blocktable definition.

Bonus Feature

The table markup described above can actually be any kind of markup, not necessarily a table. You could, for example use this module to embed your blocks in an HTML list or any arbitrary HTML. I don't have a particular use case for this in mind, but the capability is there.