CHAPTER 10 ■ WORKING WITH BLOCKS

Although the block API is relatively simple, don’t disregard the complexity of what you can do within that framework. Blocks can display just about anything you want (that is, they are written in PHP and thus are not limited in what they can do), but they usually play a supporting role to the main content of the site. For example, you could create a custom navigation block for each user role, or you could expose a block that lists comments pending approval.

Block Configuration Options

A common configuration option that you’ll want to become familiar with is setting the block visibility options on the configuration page for a block. Block visibility defines when a block should and should not be displayed on a page based on criteria you specify using the interface shown in Figure 10-2. Using the User Login block as an example, you can control whether the block is displayed through the following options:

•Page-specific visibility settings: Administrators can choose to make a block be visible or hidden on a certain page or range of pages or when your custom PHP code determines that certain conditions are true.

•Content types visibility settings: Administrators can choose to display this block only on pages that display a specific content type—for example, display this block only if the page displays a forum topic.

•Role-specific visibility settings: Administrators can choose to make a block be visible to only those users within certain roles.

•User-specific visibility settings: Administrators can allow individual users to customize the visibility of a given block for that user within his or her account settings. Users would click their “My account” link to modify block visibility.

226

CHAPTER 10 ■ WORKING WITH BLOCKS

Figure 10-2. Configuration screen of a block in the administrative interface

Block Placement

I mentioned previously that the block administration page gives site administrators a choice of regions where blocks can appear. On the same page, they can also choose in what order the blocks are displayed within a region, as shown in Figure 10-1. Regions are defined by the theme layer in the theme’s .info

227

CHAPTER 10 ■ WORKING WITH BLOCKS

file, rather than through the block API, and different themes may expose different regions. Please see Chapter 8 for more information on creating regions.

Defining a Block

Blocks are defined within modules by using hook_block_info(), and a module can implement multiple blocks within this single hook. Once a block is defined, it will be shown on the block administration page. Additionally, a site administrator can manually create custom blocks through the web interface. In this section, we’ll mostly focus on programmatically creating blocks. Let’s take a look at the database schema for blocks, shown in Figure 10-3.

Figure 10-3. Database schema for blocks

Block properties for every block are stored in the blocks table. Additional data for blocks created from within the block configuration interface is stored in other supporting tables, as listed in Figure 10-3.

The following properties are defined within the columns of the block table:

bid: This is the unique ID of each block.

module: This column contains the name of the module that defined the block. The user login block was created by the user module, and so on. Custom blocks created by the administrator at Structure -> Blocks -> Add Blocks are considered to have been created by the block module.

delta: Because modules can define multiple blocks within hook_block_info(), the delta column stores a key for each block that’s unique only for each implementation of hook_block_info(), and not for all blocks across the board. A delta should be a string.

228

CHAPTER 10 ■ WORKING WITH BLOCKS

theme: Blocks can be defined for multiple themes. Drupal therefore needs to store the name of the theme for which the block is enabled. Every theme for which the block is enabled will have its own row in the database. Configuration options are not shared across themes.

status: This tracks whether the block is enabled. A value of 1 means that it’s enabled, while 0 means it’s disabled. When a block doesn’t have a region associated with it, Drupal sets the status flag to 0.

weight: The weight of the block determines its position relative to other blocks within a region.

region: This is the name of the region in which the block will appear, for example, footer.

custom: This is the value of the user-specific visibility settings for this block (see Figure 10-2). A value of 0 means that users cannot control the visibility of this block; a value of 1 means that the block is shown by default but users can hide it; a value of 2 means that the block is hidden by default but users can choose to display it.

visibility: This value represents how the block’s visibility is determined. A value of 0 means the block will be shown on all pages except listed pages; a value of 1 means the block will be shown only on listed pages; a value of 2 means that Drupal will execute custom PHP code defined by the administrator to determine visibility.

pages: The contents of this field depend on the setting in the visibility field. If the value of the visibility field is 0 or 1, this field will contain a list of Drupal paths. If the value of the visibility field is 2, the pages field will contain custom PHP code to be evaluated to determine whether to display the block.

title: This is a custom title for the block. If this field is empty, the block’s default title (provided by the module that provides the block) will be used. If the field contains <none>, no title will be displayed for the block. Otherwise, text in this field is used for the block’s title.

cache: This value determines how Drupal will cache this block. A value of –1 means the block will not be cached. A value of 1 means that the block will be cached for each role, and this is Drupal’s default setting for blocks that do not specify a cache setting. A value of 2 means the block will be cached for each user. A value of 4 means that the block will be cached for each page. A value of 8 means that the block will be cached but will be cached the same way for everyone regardless of role, user, or page.

Using the Block Hooks

The block hooks—hook_block_info(), hook_block_configure(), hook_block_save(), and hook_block_view()—handle all the logic for programmatically creating blocks. Using these hooks, you can declare a single block or a set of blocks. Any module can implement these hooks to create blocks. Let’s take a look at each of the hooks:

229