What is the difference between doLayout and include in a template in 'Java Play!'?

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.

Answer 2

From the google-group I noticed the differences between extends (doLayout), include and a tag:

extend and include are similar, the difference is mainly in the way that you pass around variables

With extend, the parent template provides the boilerplate, and the child template provides the "body". For example the parent template could render a header and footer, and the child template could render the main content of the page. You typically set variables in the child template that are read and applied in the parent template eg #{set title:'Pet shop' /} or #{set showLoginBox:true /}

You use include when you want to do the same thing many times within a single parent template. For example #{include 'formStatusFields.html' /} The variables in the parent template are available to the included template.

If you have a piece of template code that is executed from multiple different parent templates, you should use a tag. You can pass variables to a tag. eg #{button label:'Ok', id:'ok-button'}