Boxes Abridged

This post is part of our Abridged series, which aims to explain the basics of some of the more ominous yet awesome Drupal projects in simple and practical terms. We hope these posts will help demystify some of these projects for people who have been hesitant to try them out!

Here, we'll take a look at Boxes module, including a review of its history within the Drupal project, the current state of the module, how to start using it, how we use it at Affinity Bridge, and some resources. Special thanks to Tylor who recently did a sitdown (team discussion/learning session) on Boxes module, and wrote the technical sections of this post.


Boxes module is a Drupal project that 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.


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 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, 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.

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.

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).

Current state

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.

How to use it

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.


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/ 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.

How we've used Boxes at Affinity Bridge

Multi-field blocks
We needed site admins to be able to create and update icons on blocks on a whim through the admin UI, so we created a custom box type with an image field. The blocks on the Teachers Without Borders (TWB) Get Involved page each have the same structure, but have custom fields for the icon, link, and link text so they can also be themed consistently.

Welcome to the CTM! | Teachers Without Borders Groups Collaboration AreaBlocks 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. On the TWB Groups site (built with Open Atrium), we had blocks that needed to be translatable into multiple languages. To solve this, we used Boxes to provide different fields for each language, which allowed us to expose that block content to the user in the right language context.

You can see this in action on the "Collaborate" block in the sidebar of the TWB Groups site - the English and Spanish versions 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 (click image on right to zoom).

Displaying Searchlight driven gRaphael content in blocks
On the Center for Health Market Innovations (CHMI) homepage, Development Seed (who originally built the site) 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. We've extended this functionality to add new blocks on the Programs page sidebar.

You can read more about the use cases for Boxes on the Development Seed blog. A lot of the extensions that are seen on the CHMI site are also used on, and there's more detailed info on their implementation on these posts about building data browsers with Drupal and mapping public health data.


(Boxes Monster graphic used for homepage thumbnail for this post c/o Development Seed)


thanks for the post. helps

thanks for the post. helps explain things

I would say that there is no

I would say that there is no longer any reason to use blocks. To add to your list of when to use hook_block() would be for blocks that have a layout too complex to trust a WYSIWYG editor not to mangle (floats, custom image sizes, etc.).

In regards to D7, boxes is unfortunately still very beta. The WYSIWYG integration is a little broken. And the edit-in-place can often mangle the page - though I imagine that this will be switched to use contextual links sooner or later.

Thanks for highlighting

Thanks for highlighting Boxes! It deserves more attention.

Thanks for the comments!

Thanks for the comments! Dalin - that is another good one, it'll be interesting to see how Boxes progresses in the context of the Web services + context initiative (or if it's impacted).

More Details About Charting?

I've had another request come my way for the best way to to good looking, Views-integrated graphing. gRaphael looks great, but the state of Views integration is "in progress". Will there be code or further discussion about how gRaphael was given the data?

Searchlight gRaphael

In our case the data was taken from Searchlight facet info, so it hides the views integration. I'm noticing now that this is publicly available, take a look:

Custom Box with not working with language and context

I have a custom box and put that on left of dashboard context. I want this box to be translatable. For this I have taken separate boxes (for each language). I have select the language for each box in block configuration. But all the boxes are showing on the dashboard and there is no effect of changing language.

Any suggestion, how to solve this ?

CSS selectors that make sense

Boxes also creates values for the id's property that it make more sense than the usual "block-block-1", thanks to the machine name that you use when you create your box.

For example the id for the "Our Members" box in the Teachers Without Borders (TWB) site that Ariane mentioned before is "block-boxes-about_our_members", and not only make more sense but it also helps to identify your CSS selectors.

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

More information about formatting options