Pushing the envelope with Display Suite

If you've done the odd Drupal job, you're probably familiar with Drupal's build modes. A build mode defines the way Drupal builds and presents a node to the user. Drupal core comes with a few default build modes such as 'Teaser' and 'Full node'. If you want to step sideways and - depending on the context - need extra display variants for a node (in blocks, in views, full pages,...) you'll probably end up falling back on Drupal's template suggestions. But even when you're careful, it's an easy road to perdition, clogging your theme with more template files (Views templating anyone?). Not to mention the hairy CSS you're forced to write.

No more.

These days, there are solutions which make life a tad easier.

Panels has been around for some time and other modules like Context and Boxes are very promising. The new kid on the block is Display Suite which gives you fine grained control over individual fields and build modes. At Krimson we've been using Display Suite for some time now and we can't imagine how we lived without it. If you want to get up to speed with Display Suite, you should watch Swentel's excellent introductory screencasts and the Display Suite Session from DrupalCon San Fransisco.

This article is a first of a series in which we will discuss several techniques which will make stuff most Drupal developers used to dread, actually fun to implement.

Suppose you have two content types called 'cook' and 'recipe'. Cook nodes refer to recipe nodes (many-to-many) through Node Reference. On the detail of a full Cook node, you want to display a list of referring recipe nodes. Preferably showing the recipe fields of your own choice.

How do we go from here? Normally, one would start mucking around with templates, views_embed_view(), custom code and such. Display Suite allows us to do this with zero code.

1. If you haven't done so: install and enable Display Suite, Node Display and Node Contributions.

2. Go to 'admin/ds/layout'. You'll get a list of all available build modes per content type.

3. Clicking 'edit' next to the 'Full node' build mode for the 'Cook' content type, you will discover a 'display fields' panel from CCK on steroids. Display Suite partitions the build mode display into 6 predefined separate regions. You can easily group fields into those regions.

4. You should see the 'Recipes' CCK field among the list. This is your node reference field. Drag and drop it in a region.

5. In the 'format' column, you can set a formatter per field. By default, you'll get a 'default' formatter and - depending on the field - a few others. Since DS plugs into Drupal's Input Format API, this also supports ImageCache and even your own custom formatters. You'll notice that the Node Reference field also lists 'Build mode: x' formatters. Yep, these are build modes associated with the referred content type. Select the build mode you wish to use i.e. "Teaser".

5. Go to the 'Recipe' content type in 'admin/ds/layout' and edit the build mode you've just selected on the 'Full node' build mode for the 'Cook' content type. So if you chose to show the recipe's teasers, you edit the build mode 'Teaser'.

Now create a Cook node and a few recipes. Go to the full node display of the Cook node and enjoy your handy work. It will show the entire "Full node" build mode for the Cook node but it will also list the associated Recipe nodes shown in the selected build mode.

The Node Edit form:

The full node view:

Instead of going with 'Teaser', you could also create your own Build Mode from 'admin/ds/nd/buildmodes' and implement that one for the 'Recipe' content type. Yes, you can also do the same for the Cook content type and start combining 'Cook' and 'Recipe' build modes.

This is the fastest route to generate a list referred nodes within a build mode of a referring node. And it gives you a lot of flexibility. Still, this list isn't really controllable. There is no easy way to add conditional behavior. Suppose the referred nodes were events which are only visible on the list until they have passed?

Views comes into play here. In the next article of our series, we will show you how to leverage the flexibility of Views within Display Suite