Custom display suite template

Question

I'm trying to understand Drupal 8 theming, since I want some custom layouts for some of my pages. I've tried Display Suite module, and it gets me some of the way, but non of the display suite layouts offers the exact layout I need.

How do I make my own Display Suite layouts? I have made a copy of the layout template files from ds/templates to mythemename/templates/generated, and renamed the file as Display Suite tells me to. When I open that file, I see Header, Left, Right and Footer "regions". But how would I go about adding new regions to that template? I understand how to add block-regions to a website, but that seems to be something different than the "regions" in a display suite template.

And if I edit a display suite template, would I somehow be able to rename it to, lets say, "mytemplate", and make it appear in the drop-down box from where you select what display-suite template to use?

Answer 1

You can create your own layouts in a module or theme by defining a my_module.layouts.yml or my_theme.layouts.yml file. Then you'll have to create the templates for your layouts where you output the regions.

This is the layout definition for the DS 2 Col Fluid layout (ds.layouts.yml):

ds_2col_fluid:
  label: Fluid two column layout
  category: Display Suite
  class: '\Drupal\ds\Plugin\DsLayout'
  type: partial
  template: templates/ds-2col-fluid
  library: ds/ds_2col_fluid
  icon: images/ds-2col-fluid.png
  regions:
    left:
      label: Left
    right:
      label: Right

label defines the label that's displayed when you're selecting your layout on the Manage Display screens.

category defines the option group that your layout appears in on the Manage Display screen. It can be helpful to use My Module or My Theme here to group all layouts defined by your module or theme.

class I've never had to change this to anything else to anything other than \Drupal\ds\Plugin\DsLayout

type I've never set this to anything other than partial. I'm not sure what the other options are.

template defines the template file to use. This should be the relative path, from your module or theme, to the template.

library allows you to load a drupal library as a dependency when you're layout is being rendered. Add js or css that you may need.

icon defines the path to the icon that appears on Manage Display screens to represent your layout.

regions define the regions of your layout.

As far as I know you don't need to include the icon or library parameters and it won't cause any errors.

Your template file will have variables for content, attributes, html element for each region, layout and outer wrapper. See ds/templates/ds-2col-fluid

Here's an example for how you can render a region you defined in your layouts.yml file (taken from ds/templates/ds-2col-fluid):

{% set left = left|render %}
{% if left %}
  <{{ left_wrapper }}{{ left_attributes.addClass('group-left') }}>
    {{ left }}
  </{{ left_wrapper }}>
{% endif %}

If you define your layouts and templates in a module file, you can later override the templates in a theme if needed, as you can with any standard template in drupal.