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.

Background

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.

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.

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.

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.

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.

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. 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 http://data.worldbank.org, and there's more detailed info on their implementation on these posts about building data browsers with Drupal and mapping public health data.

Resources

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