Last updated June 21, 2013. Created by arianek on June 20, 2011.
Edited by jeffschuler. Log in to edit this page.

Boxes module was originally built by Jeff Miccolis from Development Seed. It's been around for quite a while, but many people don't venture into using it, largely because it's not clear upfront what the benefits are over core Blocks.

History

Jeff Miccolis summed up the history:

Earlier this week I added the Boxes module, which provides custom blocks that play nicely with Spaces and Ctools, to Drupal.org. I initially wrote the module for recent work we did on the World Bank's Open Atrium-based intranet, and at first I wasn't sure if it would be something that we'd want to maintain and release on Drupal.org, as it seemed rather project specific. However after using it on this project, it became apparent that we'll want to use the Boxes module on many projects and that the module could play a large role in making Open Atrium stronger out of the box.

Current state

It has since become part of the "Dev Seed stack" (ie. Features, Context, Spaces, Boxes, Searchlight, etc.), used by many teams who subscribe to their methodology of saving as much configuration in code as possible, and simplifying deployment processes.

The Boxes module is now maintained by Frank Febbraro from Phase2 Technology, and is still in active development. It is one of the modules that is used in the Open Atrium Drupal distribution, which they now own.

Uses

Block vs. Boxes

Boxes is really a full replacement for block; as it says on the Boxes module page, "Boxes module is a reimplementation of the custom blocks (boxes) that the core block module provides. It is a proof of concept for what a re-worked block module could do."

That said, it's extremely similar to the core Block module but also gives you:

  • Exportability (configuration can be captured in features + deployed easily, module is dependent on CTools)
  • The ability to easily extend blocks and add custom fields (all you need is a delta/machine name and description, and then add new fields using the Drupal FormAPI).
  • The option to edit in place (and with WYSIWYG editor).
  • Solid integration with Context and Spaces, i.e. a block can be overridden and defined for each space, for example per group.

Unlike Block and hook_block, Boxes uses its own database table to automatically handle storage and retrieval of custom field values, rather than making you define it for yourself. Traditionally with Block, this is done with variable_set and variable_get or a custom table. Also, it's interesting to note that Boxes uses hook_block() and is simply building on top of what Drupal already provides for defining blocks.

When to use boxes

  • When you want to create a structured custom block with multiple fields.
  • When you want to create a block that will be used in a multilingual site (so you don't have to create one block per language).
  • When you want to create a custom block that displays data from an API, Searchlight, or gRaphael.
  • When you want your block configuration to be exportable.

When to still use block or hook_block()

  • When you want to create simple blocks with just a title and description, block module is very good at that.
  • When you want to create a block whose content is generated programmatically, highly custom, doesn't need to be edited, and only ever used once (or not easily generalized).

Configuration

The easiest way to get familiar with Boxes is to look at the boxes_simple Box, which is included with the module. This custom box type is a replacement for Drupal's default blocks and simply provides a body field and text format (admin description, title, and machine name are always provided). You can create a new boxes_simple Box at Administer > Site Building > Blocks > Add box, and once created it will show up in the normal block list. The box can then be placed on a page using Drupal's block visibility (place it in a region and click 'configure' next to the box name to restrict where it shows up) or the Context module. The box will also show up on the Features module admin screens under the 'Boxes' section and allow exporting the configuration into code. If the box has changed, the feature will show up as overridden.

Extending

Unfortunately there is very little documentation for how to extend boxes and create custom box types; it isn't too difficult but there are a couple things to keep in mind. Extending boxes is done by defining plugins for boxes which extend the boxes_box base class (boxes are objects). To define plugins, you need to implement:

  • hook_ctools_api() - Tells ctools that there are Boxes plugins in the module.
  • hook_boxes_plugins() - Tells Boxes the box machine name (the key of the plugin array), human readable title, implementing class, parent class (usually boxes_box), class file name, and where the class file is located.

The easiest way to see how this works is to look at boxes_ctools_plugin_api() and boxes_boxes_plugins() in boxes.module and look at how boxes_simple is defined. The actual class plugin code to implement a custom box usually resides in its own file, for example boxes_simple is in plugins/boxes_simple.inc. This class extends the boxes_box class and implements three key methods:

  • options_defaults() - Tells Boxes the form defaults and what is stored in the database.
  • options_form() - Tells Boxes the form to use, which is built with the Drupal FormAPI. Defaults and existing values can be accessed from the $this->options variable.
  • render() - Return an array containing the delta (machine name), title, subject, and content of the block. This is returned directly to hook_block and follows the same format. Defaults and existing values can be accessed from the $this->options variable.

Once you've implemented these functions, the new box type will show up in Administer > Site Building > Blocks > Add My custom box.

Examples of customizations

Multi-field blocks

If you need site admins to be able to create and update icons on a set of blocks on a whim through the admin UI, you can create a custom box type with an image field. The blocks on the page will then each have the same structure, but have custom fields for the icon, link, and link text so they can also be themed consistently.

Blocks on a multilanguage site

If you've had to configure blocks on a multilingual site, you know how painful it can be setting up a separate block for each language, then linking them together manually. With boxes, if you have blocks that need to be translatable into multiple languages, you can provide different fields for each language, which then allow you to expose that block content to the user in the right language context. For example an English and a Spanish version would display the exact same block, but show the appropriate language text field by checking the $language global on render. The editing form is straightforward, a single block configuration page with a field for each language.

Displaying Searchlight driven gRaphael content in blocks

You can extended the base box to contain configuration options for Searchlight-driven gRaphael blocks. The configuration includes a graph display type (pie, bar, line, etc.) and facet info (taxonomy term facets to show), and it counts and graphs the results. This configuration is all set in the blocks, and is fully exportable and integrated with Searchlight.

Resources

You can read more about the use cases for Boxes on the Development Seed blog. There's more detailed info on their implementation on these posts about building data browsers with Drupal and mapping public health data.

Other references

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.