Question

When extending with doLayout you can only have one sub-template, but you can include more than one.

What is the difference, and what is the best practice?

Answer 1

They are kind of inverse of each other.

doLayout is used as part of the extends tag. The extends tag specifies which template you wish to extend, and the doLayout tag specifies where in the extended template your code is injected.

The include tag simply specifies that another template should be injected at the point specified.

So, doLayout works in a similar way to include, except the doLayout tag does not specify which template is being injected. This is done by the extends tag, and means that the template (which usually contains headers, footers and common css and javascript), can be extended without it needing to know anything about the template that is extending it.

Include, is just a dumb injection of code.

If you wanted to achieve the doLayout functionality with includes (and this is the way you would do it in PHP or something similar), you could do

#{include 'header.html'}
your template code
#{include 'footer.html'}

This would have to be replicated on every page in your template. Whereas using extends and doLayout allows you to simply do

#{extends 'template.html'}

And where your code is injected into the template.html is managed by the doLayout tag.

The extends approach is simply a neater way. Also, if you decide to change the layout of your page, you only need to update one file, and gives your more flexibility with where you content is located inside your extended template.