In the Manage Displays page for a Content Type there is a link 'Add display mode'. Using this I can name and configure an alternative display mode but I cannot find how to use this instead of the default. Can the machine name be used as part of a URL?
I have looked in our manual at 'Deep dive: Display Settings' but cannot find the answer there. Also it confused me regarding 'display mode' and 'view mode' - are these the same thing?
OK, I almost missed the great use of display modes for Backdrop CMS.
In Layouts, you can create a custom blocks that will display the node contents using whichever display mode you prefer. So you could override the normal display of "post" nodes with a block that uses your preferred custom display.
If you need additional help understanding how to do this, let me know. But, this would be a common and powerful use case with Backdrop CMS.
Sorry for the slow response. I didn't have a quick answer for you at the time, but I'll take a stab at it now.
First of all, you are not the only one that is confused by the terms 'display mode' and 'view mode.' https://github.com/backdrop/backdrop-issues/issues/2342
The most common way that users use different display modes is when using views. I can display a view of my "post" nodes using any custom display mode.
Here is an example of me using a display mode I named "custom" (I should have thought of something better) instead of the default which would have been "teaser":
If you are able and interested in creating custom templates, you can create custom templates for any display mode, just by naming the template correctly.
If I create a custom template for my custom display mode, views will use that custom template including whatever custom mark-up I have included.
Some other display modules might ask you which type of display you want to use for your nodes and you can choose between 'default', 'teaser', or whichever 'custom' display mode you have created.
I know there are many situations where you might have this choice, but I'm not thinking of them right now. Certainly, in your custom code you might want to call or use a custom display for nodes.
Views is by far the most common use case, I think.
Sorry for the slow response. I didn't have a quick answer for you at the time, but I'll take a stab at it now.
First of all, you are not the only one that is confused by the terms 'display mode' and 'view mode.' https://github.com/backdrop/backdrop-issues/issues/2342
The most common way that users use different display modes is when using views. I can display a view of my "post" nodes using any custom display mode.
Here is an example of me using a display mode I named "custom" (I should have thought of something better) instead of the default which would have been "teaser":
If you are able and interested in creating custom templates, you can create custom templates for any display mode, just by naming the template correctly.
If I create a custom template for my custom display mode, views will use that custom template including whatever custom mark-up I have included.
Some other display modules might ask you which type of display you want to use for your nodes and you can choose between 'default', 'teaser', or whichever 'custom' display mode you have created.
I know there are many situations where you might have this choice, but I'm not thinking of them right now. Certainly, in your custom code you might want to call or use a custom display for nodes.
Views is by far the most common use case, I think.
OK, I almost missed the great use of display modes for Backdrop CMS.
In Layouts, you can create a custom blocks that will display the node contents using whichever display mode you prefer. So you could override the normal display of "post" nodes with a block that uses your preferred custom display.
If you need additional help understanding how to do this, let me know. But, this would be a common and powerful use case with Backdrop CMS.
Hmm, this doesn't really work. Adding an Existing Content block, you can choose the Display Mode alright, but then you have to specify a Content title or ID. By default it displays ID #1. I can't see how to display the content of whatever node is being displayed. If there are Tokens for displaying the current page contents, they're not listed.
Actually it seems like the Display Mode option selector box should be part of the Main Page Content block, but it's not there. When you add a block to display the main page content is where you should be able to choose which format to use, right?
You are correct and I just opened an issue with your suggestion to "Allow 'Main Page Content' block to use a specific display mode."
https://github.com/backdrop/backdrop-issues/issues/4341
If you think this is an important issue, please comment in the issue queue.
In the meantime, there is a work around for using a display mode in a layout. You could create a view block with a contextual filter that only displays nodes of type "X" using whichever display mode you like. If this view is available as a block, you can then add it to your layout and remove the "Main Page Content" block.
(If anyone reads this and doesn't understand, please ask for further explanation. I don't have time right now.)
Thanks stpaultim for both these examples - I hope your excellent explanations can now be included in our manual. I have been building sites with Backdrop for 4 years now and have never yet made use of this 'Display Mode' way of creating custom displays, so it's great to learn a new option.
Another use for Display modes are for reference fields. My post also contains some info on theming display modes.
Let's say you have an Event and Artist node types, and you reference the Artist nodes from the Event edit page via a Reference field (called 'field_artist_reference').
In the Display mode for the Event node type you can choose how to display the Reference field ('field_artist_reference'). The default is a list of the title (confusingly called Label) of each Artist node that has been referenced. You can configure this to be a link to each node that is referenced.
You can also choose to have a "Rendered Entity" which will display the full node content of the referenced Artist nodes within the Event node. Display modes allow you to fully customise how these Artist nodes display.
In the past I've used Views or Panels to customise the display these sort of referenced fields, but Display mode makes it really easy.
As regards themeing, you may not be able to get the exact HTML theming you require with the Display mode UI, but fortunately it's really easy to use node.tpl.php templates to achieve any level of customisation. Indeed you could use the field.tpl.php templates for further refinement. I'd recommend the Devel module to help you identify which templates and naming conventions are available to you.
So, if you set up a new Display mode for Artist nodes called 'My Artist Display Mode' (machine name: my_artist_display_mode). Then you can choose which fields you want displayed, and their configuration.
Next, you can add theming code to your node template.
In this case in a 'node--artist.tpl.php' (assuming 'artist' is the machine name of the node type) file you can simply use:
<?php if ($view_mode == 'my_artist_display_mode') { ?>
to tell the template what to display when the 'My Artist Display Mode' is used anywhere in the site.
Don't forget to add, after your theme code:
<?php } ?>
to close the if statement. You'll also need to add if statements in the same file for any other display modes (teaser, full etc.)
That's easily done for the default display mode (full) like this
<?php if ($view_mode == 'full') { ?>
<--TEMPLATE CODE HERE-->
<?php } ?>
So it's possible to have all your display template code in one file!
This extends what was possible in D7 (through the use of additional modules or custom coding to generate View modes) and brings it into core. Much easier!
Obviously the theming part of my post applies to the previous use-case answers above, so I hope this has been clear and helps someone, somewhere.
You are correct and I just opened an issue with your suggestion to "Allow 'Main Page Content' block to use a specific display mode."
https://github.com/backdrop/backdrop-issues/issues/4341
If you think this is an important issue, please comment in the issue queue.
In the meantime, there is a work around for using a display mode in a layout. You could create a view block with a contextual filter that only displays nodes of type "X" using whichever display mode you like. If this view is available as a block, you can then add it to your layout and remove the "Main Page Content" block.
(If anyone reads this and doesn't understand, please ask for further explanation. I don't have time right now.)