An introduction to Display Suite

Drupal is a great framework when it comes to managing a large variety of data. The contributed module CCK makes it easy to define how you want to organize that data in content types,  and with Views you have a powerful tool to query that data and make all kinds of lists.

But despite the elaborate theme layer with numerous theme functions and template files, there is no decent way to handle the display of your data. Enter the Display Suite. This post is a short introduction for the module that will totally change the way we theme in Drupal.

What is this Display Suite?

In short: DS offers a visual and centralized way to handle the display of all your content, including nodes, users, comments etc.

First off all, you get several 'build mode' tabs per object, and by object I mean a content type, user, view etc. A build mode is a Drupal term and its best known examples are the full node and the teaser build mode. Each of those tabs represent a drag and drop interface where you can choose which fields to show and how to position them into one of 5 predefined areas, without the use of template files.

Let's look at a small example to  clarify the concept. For this site, I have one content type: blog, for which DS offers 3 relevant build modes: Full node, teaser and search results. Have a look at my settings for the blog teaser:

All the fields defined by Drupal and CCK are available for me to show or hide. I chose to show the title, taxonomy terms, the body and the links for my teaser. For the full node or search build mode, I can easily select some other fields. Drag. Drop. Cool? Definitely!

Before we continue with a more in-depth look, I should point out that DS is in fact an API that is used by different modules such as Node Displays, Comment Displays, User Displays, Views Displays., so you will need all of these modules to get the full power of DS. For the simplicity of this post, I will focus on ND and thus content types.

Why should you use it?

Build modes

As mentioned you will see a tab per build mode for every content type. Drupal defines these build modes automatically: Full node, Teaser, Sticky, RSS, Search Index, Search Result and Token. Not all of them are relevant, but you should recognize full node, teaser, sticky and search result. Having a way to easily display different fields for any of them is a blast.

But it doesn't stop there. You can just as easily create new build modes. Typically, I would create an extra build mode called 'Sidebar list', which would contain even less fields than the teaser build mode, and fit nicely in a sidebar block, such as  'Related posts'. Using these extra build modes brings us to the next benefit: Views integration.

Views integration

By default, Views offers two options for 'Row style': Node and Fields. DS adds a third 'row style', where you can select one of the build modes you created.

Let's say I would have several blog blocks created by views: new posts, old posts, popular posts, most recent posts etc. I want those lists to show the blog title and the post date, so I use my newly created 'Sidebar list' build mode for that, and configure all my views to use that build mode. A few days later, I might decide that I also want to show the taxonomy terms. I simply go to the right blog build mode in DS, drag that field in the middle region and that's it. I don't have to go to every one of those views and change the fields there. Central management is what it is all about.

Fields and labels

Let's have a closer look at those fields. Of course you get the ones that you would expect: title, body, links etc. As a nice touch, DS already adds a 'read more' field, useful for teaser displays. Even better, nothing stops you from adding your own fields, although you will have to do some PHP coding for that. An example of an extra custom field could be the picture of the author of a blog post.

Ever wanted to change the label of a field, but didn't want to create a template just for that? No worries, with DS you can choose wether you want to show it or not and as easily change its value.

Formatters

Now that you have all your fields, you might want to tune the output a little. That where the format column comes in. For example the title comes with several formats: H1 linked to node, H1, H2 linked to node, H2, H2 block title, H2 block title linked to node, etc. Another example is that every image field can be formatted using your pre-defined Imagecache formats.

Again, through PHP coding you can add custom ones, but DS offers the most common ones out of the box.

Styles

Similar to the formatters, there are styles (as of version 1.1). A style is basically a class that you can define yourself and apply to any of the available fields. For example if you want to add a nice border around some fields, define a 'border' class once and apply it to your fields. That means you only have your CSS defined once, which is good for clean CSS.

My personal favorite is an 'inline' style that allows to position fields next to each other in a simple way.

Regions and fieldgroups

The 5 predefined regions offer quite some flexibility as you get a header, followed by a middle region with a left and right sidebar, and a footer. Don't confuse this with page regions, but see them as mini regions within your node. Also note that the sidebars will collapse if they are empty.

If these 5 regions are not enough to get the display you want, you could also create a DS fieldgroup (as of version 1.1), allowing you to group your fields together for display, with the option of displaying it as a fieldset or a simple div.

Conclusion

This introduction only scratches the surface, but should give you an idea of its main concepts: central layout management, clean CSS through reusability and optimal flexibility to expand DS to fit your needs. So forget nightmare themes with too much complex node templates, views templates, theme functions and a huge pile of CSS in a desperate attempt to glue it all into one cohesive look and feel. Do you really want to dive back into that when the customer decides to add or remove some fields?

All feedback is welcome!