You’ve just installed a fresh Drupal 8 website, created a few content types and attached fields to them. So far so good.
Now you want to customize the content pages. On the “Manage display” page you can re-order fields and disable them but you can’t move them into any type of region.
Display Suite enhances the “Manage display” page by offering a drag-and-drop interface for fields.
You can select different layouts and each layout has its own set of regions. The drag-and-drop interface then is used to move fields into these regions, all without writing a single line of code.
The real benefit in using Display Suite is you always have a standard workflow for modifying content pages.
If you’re working in a team, this is even more important; you want to standardize how entity types are customized. Or you’ll end up in a situation where each developer does things their own way.
In this tutorial, you’ll learn how to modify the Article content type layout using Display Suite.
UPDATE May 2017: Layout plugin is no longer required from Drupal 8.3 and onwards. Just install Layout Discovery which comes with Drupal core.
Before we begin, go download and install Display Suite.
$ drush dl ds $ drush en ds
$ drupal module:download ds --latest $ drupal module:install ds
Modify “Full content” View Mode [watch on YouTube]
To modify the Article content type, go to Structure and click on the “Display Suite” link.
From this page, you can jump directly to the “Manage display” page for specific entity types and you can modify other Display Suite settings.
Now, click on “Manage display” on the Article row.
Access “Manage display” from Content Types Page
You can also access the “Manage display” page by going to Structure, “Content types” and click on the down arrow then “Manage display”.
Both links send you to the same page so it doesn’t matter which is clicked on.
Enable “Full content” View Mode [watch on YouTube]
Scroll down and click on the “Custom display settings” vertical tab, select “Full content” and click on Save.
This will enable the “Full content” view mode which is used when viewing the article on its own page.
Now at the top you should see a “Full content” tab, click on it.
What’s with the Default view mode?
I personally avoid the Default view mode if possible, it’s used as a fallback. If Drupal displays an entity with a disabled view mode it’ll fallback to the default one.
So just remember, if you want to customize how an article looks on its own page, then enable and use the “Full content” and leave the Default view mode as simple as possible.
Select Layout [watch on YouTube]
To enable Display Suite on a view mode, scroll down to the vertical tabs and select a layout from the drop-down.
Select “Two column stacked layout” and click on Save.
You should now be able to move fields into different regions. Go ahead and add the fields into the following regions:
- Move Body into Left
- Move Image, Tags and Links into Right
- Move Comments into Footer
Don’t forget to click on Save.
At this point, you’ve successfully modified the Article content type using Display Suite.
Enabling Display Suite on a view mode is straightforward. Just select a layout on a specific view mode and that’s it.
Now that everything has been configured, go and create a test article, it should look like the image below:
Override Layout Template [watch on YouTube]
So far you’ve learnt how to setup Display Suite on the Article content type. We’ve setup the “Full content” view mode to use the “Two column stacked” layout which comes with the module.
What if you want to modify the layout? Luckily, the layout is a template and it can be overridden like any other.
The layout template location and template suggestions can be found on the “Manage display” page.
In the image above, you can see that the
ds-2col-stacked layout is in “modules/contrib/ds/templates”.
The filename should be
ds-2col-stacked.html.twig. Simply copy the template into your theme and adjust the filename based off the template suggestions, then rebuild the cache.
Now you’re ready to modify the template whichever way you want.
Change Wrapper HTML Tags in Layout [watch on YouTube]
Before you start overriding templates, if all you want to do is change which HTML tag is used for a region then take note of this option.
From the “Custom wrappers” vertical tab, you can change the wrapper HTML tag on regions and the layout.
So if you were to select Footer from the “Wrapper for Footer” drop-down. The Footer will be wrapped with a
<footer> tag instead of
Add Custom Classes to Regions [watch on YouTube]
Changing the wrapper is useful but you can also add custom classes to regions. This will help designers apply specific styles to certain regions.
If you click on the “Custom classes” vertical tab, on the “Manage display” page, you’ll see the message “You have not defined any CSS classes which can be used on regions.”
Click on the “Manage region and field CSS classes” link and enter in the following into “CSS classes for regions”.
Once you click on “Save configuration”, you should be redirected back to “Manage display”.
Now in “Custom classes” you should see the following, here you can choose multiple classes for any of the regions.
All selected classes will appear on the wrapping element.
I really see Display Suite as a must have module. You can do a lot with it just by using its interface. But if that’s not enough, you can override layout templates and even implement custom layouts.
Q: I can’t see the “Custom wrappers” or “Custom classes” vertical tabs?
The vertical tabs will only appear once a layout has been selected.
Q: I need to rebuild cache when I change anything in a Twig template.
Twig templates are heavily cached. Even the rendered results of a template is cached.
You’ll need to turn on Twig debug to stop it from caching (learn how to turn on Twig debugging). But make sure you turn off debugging before going live.