Display Suite is one of the essential modules which I use on every project. It allows you to change the look and feel of entity bundles, i.e., content types, vocabularies, users and much more. Building custom layouts and adding fields is a breeze, but there’s another feature you may not be aware of and that’s custom field templates. Display Suite allows you to change the markup which is used to render individual fields.
The functionality to change field templates is off by default. To turn it on, you’ll need to enable the “Display Suite Extras” sub-module and check the “Field Templates” on the Extras page.
In this tutorial, you’ll learn how to enable “Field Templates” and how to use them.
Bonus: FREE 4 part mini-course on Display Suite for Drupal 8. Click here to subscribe and take your site building skills to the next level.
Step 1: Enable Display Suite Extras
I’ll assume you already have Display Suite configured and working. All you have to do is enable the “Display Suite Extras” sub-module. Go ahead and enable it.
If you’ve never used Display Suite and want to learn more about it, I recommend that you read “Configuring Layouts with Display Suite in Drupal 7”
Step 2: Enable Field Templates
Once you’ve enabled “Display suite Extra”, the only thing left to do is enable “Field Templates”. Go to Structure, “Display Suite” and click on the Extras tab.
From within the “Field Templates” field-set, check “Enable Field Templates” and click on “Save configuration”.
You can also select which template will be used as default from this page. Just leave it as “Drupal default” for now.
Using Field Templates
Now go to the manage display page of a content type that is controlled by Display Suite. I’ve setup the Article content type to use it so I’ll go to Structure, “Display Suite” and I’ll click on “Manage display” within the Article content type.
If you’ve used Display Suite in the past then you’ll notice “Field template: Drupal default” in the settings summary.
This tells you which field template is in use. At this point it’s “Field template: Drupal default”.
Just click on the cogwheel and select a different template from the “Choose a Field Template” drop-down list.
Now that you know how to enable different templates let’s look at each one in more detail.
Template 1: Drupal default
The “Drupal default” template is the most common and it’s used by default. If you’ve done any Drupal styling it should be familiar. Depending on your feelings about Drupal’s markup, you either like the flexibility or hate that there’s too much markup.
Template 2: Full Reset
“Full Reset” does what it says. It removes all field markup so what you’re left with is just the HTML from the field.
Template 3: Minimal
The “Minimal” template isn’t as strict as “Full Reset”. A single DIV with classes wraps the field value.
The template comes with a formatter option: “Hide label colon”. This option allows you to control the colon displayed in the label, if required.
Template 4: Expert
The “Expert” template isn’t really a template like the others. All it does is give you the ability to define what markup will be used via the “Formatter setting” form. If you’re pedantic about markup and want full control over what’s displayed then give it a go.
However, if you’re looking for this level of flexibility then I’d recommend you write your own custom Display Suite field. It can be very time consuming filling out the “Formatter setting” form if you want to use the same markup across multiple fields. Then again, defining a custom Display Suite field requires some coding ability.
Summary
Field templates offer an extra level of flexibility. But if you do require heavily customised fields then I would still look at implementing a custom Display Suite field.
FAQ
Q: I can’t find the “Display Suite” link under “admin/structure”.
Make sure Display suite UI is enabled.
Q: I can’t see the “Choose a Field Template” drop-down?
Make sure you enable Display Suite Extras sub-module and check the “Enable Field Templates” checkbox.
How would you recommend including data (tokens or variables?) from the entity in the field template? For example, “Template 4 Expert” let’s us add attributes to the label/wrapper/item etc… but what if we want the attribute to be dynamic based on some property/value of the entity? Like say I want to give them an `id=”123Collapse”` where “123” is the node id. I’m sure there are many ways to do this… but do you recommend a particular best practice or a “display suite” way?
Hi Alec,
I don’t think it can accept any type of token.
Unfortunately, you may have to write code to implement it.
Cheers,
Ivan
Hi Ivan! Thanks, yeah, I figured I’d have to write some code. Do you have recommendations? Like should I write a custom DS template(would block/bean id be available there?), or just a preprocess_something_or_other?
I implemented hook_block_view_alter() but apparently that’s too early in the rendering to affect the HTML.
I guess my main question is whether there’s a proper “Display Suite” way of doing this or if I should just be using core hooks?
OMG, apparently as of https://www.drupal.org/node/1598044 tokens *can* be used in expert mode! Placing [bean:delta] (and presumably any other valid token) in attributes just works 🙂
Thanks for the link.
On the last picture,
what is the difference between field item and field items? (expert mode)
Hi Thomas,
The “field items” wraps “field item”.
Just add a class to field items and it’ll be on the DIV which wraps the field item.
Cheers,
Ivan