Are you leveraging Drupal 8's Layout API?

Okay, so if you've worked with a site running Drupal 8.3.x and above, the answer most likely is yes. It may, in fact, be in use on your site without you realizing it. That is because modules like Panels and Display Suite actually leverage it to manage layouts on the site.

Layouts API can help you gain control of the presentation of your site. In fact, we are making use of it on some of our recent projects and have appreciated the power it gives us as developers while still maintaining the ability to manipulate elements in the UI. How could you use this in your projects and why would one use it directly as opposed to a layout related module? 


So "layouts" and "site presentation" maybe a little vague. So what "layouts" is this API referring to?

Drupal 8 has different types of entities that can be displayed in varying ways, the node entity type being one of them. The entities associated with these entity types have fields associated with them that we can display in any order. But that is just about it. The problem is, there are many cases where'd we like to group these fields or perform other special actions to them. But we can't! At least not without hardcoding such fields in a template.

We can define regions in a theme and place blocks within those regions just fine thus defining a page layout. But fields, that is another story!

The Layout API addresses this problem. "Layout", in this case, is referring to organizational presentation for entities rather than just pages. An entity can be a full paged node, a block, or a teaser view mode of a user. You can use this API to define layouts for those specific components!

So how can you use this on your site?

The Layout API exists within an experimental core module called Layout Discovery. It is based on the deprecated contributed module Layout Plugin which allows you to register layout for use in your theme. It also provides a plugin you can extend.

The Field Layout module, another experimental core module, allows you to use layouts in the field UI. So for example, what if I wanted to build a teaser listing where we have a title, summary, and author on the left and an image on the right of each item? We could add a two-column layout. This would make available to us two "regions" in the field UI we could place our fields into.

After moving the image field in the right region and moving the rest to the left, we'd get our desired results, assuming things were styled accordingly. Because of use cases like this, we have found these modules to be a good alternative to Display Suite! Check out this OSTraining blog post "Drupal 8's Field Layout is an Alternative to Display Suite" for a breakdown of how to use it layouts in the field UI and why it is a good alternative for Display Suite. Also, take a look at this post from us "Why We Ditched the Display Suite Module in Drupal 8".

Some layouts are available already and some may have been provided by modules or themes. These alone can come in handy but how can you create some of your own, perhaps for our teaser list items?
Here's how:

  1. Create a .layouts.yml file in your theme or module. Let's assume we are making a module called Post Layouts for providing more layouts. The file will include the name of the module. In this case, it'd be post_layouts.layouts.yml. This would go on the same directory level as your .module and .info.yml files.
  2. Add information for your layout.
    • You'd want to add a machine name, label, category, template reference, and regions in this format.
  3. Create a layouts directory in the root directory of your module. Then create a template file for your layout. You can put this in another directory. Personally, I like to create directories matching the names of the categories that were created. (Note: Make sure the reference to this template in the .layouts.yml file matches this structure.)
  4. In the template file, you can add regions that you create in the .layouts.yml file in the form of twig variables.

Once you complete those steps and enable the module if not already, you will see your layout available for use in the UI. As a side note, Layout can not only be used for the front-end, but for the back-end as well. We here at Unleashed look forward to exploring that use case!

These core layout modules have given us more power when it comes to build out different entity structures on the frontend. Have you been able to use these powerful additions on your site? Do you have plans to do so in the future?

For more information, check out the Layouts API in the Drupal 8 docs.