Tutorial series:
- How to Customize Content Pages
- How to Use Display Suite Fields
- How to Use Switch View Mode Sub-module
- Webinar: Customize Content Pages using Display Suite in Drupal 8
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.
Getting Started
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.
Below are the Drush and Drupal Console commands to download and install:
Drush:
$ drush dl ds $ drush en ds
Drupal Console:
$ 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.
Test Layout
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 <div>.
From this:
To this:
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”.
custom-footer|Custom footer
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.
Summary
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.
FAQ
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.
I have been using DS for years on Drupal 7. I really like it as a light weight layout tool for many of the reasons you mention in your post.
Recently I moved my site to D8 (still in progress), using DS there as well. Unfortunately this has proven impossible. Display Suite for D8 does disrupts the standard theming patterns in Drupal 8! Preprocess functions do not work as they should and the twig template naming scheme is such that I have not been able to understand it. So sad. I had to turn DS off!
It is a real loss. As you say, DS is a must have. But in its current state, I find it unusable on Drupal 8.
Christophe
Hi Christophe,
I’ve used DS in Drupal 8 and haven’t hit any roadblocks as you mentioned. Normally, if I need to heavily modify the content pages, I would implement custom layouts and fields.
The Drupal 8 version is different than in Drupal 7. For one thing, they use a whole new layout template system. (https://www.drupal.org/project/layout_plugin)UPDATE May 2017: Layout plugin is no longer required from Drupal 8.3 and onwards. Just install Layout Discovery which comes with Drupal core.
I do not agree with your statement that it’s unusable in Drupal 8. But maybe for your specific use-case it’s not the right tool.
Cheers,
Ivan
Hi, great and awesome video, I will keep you for good reference for other D8 topics, too!
Can you explain a bit how responsive DS is, or where won could tweak things to get great results on mobile and on desktop. Meaning how much depends on the theme and what could DS in order to improve things, like setting breakpoints or what else?!
J
Hi Jim,
The responsiveness of a website is determined by the theme, not Display Suite. Normally this would be controlled by your theme. For example, if you’re using Bootstrap then just use the correct grid classes to make things responsive.
Cheers,
Ivan
Dear Ivan,
Apart from drush and drupalconsole, I would recommend to install the modules using composer, as that is the future preferred way of installing and maintaining sites.
Hi Paul,
That’s great advice.
What composer command would you want to see on this tutorial?
Cheers,
Ivan
Hi Ivan,
Thank you so much for this post. Front-ending my first D8 site at the moment, lots of things to figure out. A question, with adding custom classes – is there any way to implement tokens in the custom classes? For example, if you want to use taxonomy term-id, or create a class programatically?
Hi Tamara,
Great question.
Unfortunately you can’t add tokens into the classes name. It’ll be a good feature though.
What you could do is override a display suite layout and add the taxonomy via the addClass function in twig.
<{{ outer_wrapper }}{{ attributes.addClass('ds-3col-stacked-equal', 'clearfix') }}>Cheers,
Ivan
Hi Ivan,
You mention in the video you like to use the ‘Full content’ view mode. What is your reason for this? Why would you recommend this (instead of using ‘Default’ for example)?
Cheers,
Tom
Hi Tom,
“Full content” is what’s is used on the /node/1 pages.
If, for example, you create a view to display all nodes using the view mode “Promo” and one of your content types doesn’t use that view mode it’ll display the Default view mode as a fallback.
However, “Full content” is always used on /node/1.
This is just the way I do it. 🙂
Cheers,
Ivan
Hi,
Just wondering which tool are you using at minute 5. Phpstorm? I mean your mac app what can browse folders, edit files, open a terminal, etc.
Thank you for your interesting video.
Hi Joan,
Yes, that’s PhpStorm.
Cheers,
Ivan
Hi
Using ds I had to tweak my preprocessor functions like the following, which is ugly, and I am still not sure that everything works. The reason is that THEME_preprocess_node is not launched for teaser, for example.
function mytheme_preprocess_ds_entity_view(&$variables) {
$variables[“node”] = $variables[“content”][“#node”];
$variables[‘view_mode’] = $variables[“content”][“#view_mode”];
mytheme_preprocess_node($variables);
}
Yes with DS the preprocess_node won’t get loaded. Just move the logic into mytheme_preprocess_ds_entity_view. Or just load, preprocess_node, like you are.