-
Notifications
You must be signed in to change notification settings - Fork 107
Templates
All materials that aid the communication of information are considered presentational elements. Layouts are used to render the content and the assets used form the presentation (images, CSS, JS and also LESS, CoffeeScript that compiles to CSS, JS) comes under this definition. Presentational elements must be placed inside the templates directory.
Layouts define how content must be presented. For each page request, Punch passes the matching layout and content to the template engine, which outputs the rendered page. The layouts must be written using the enabled template engine format.
Note: Mustache is the default template engine used in Punch. You also have the option to use other template engines, such as Handlebars instead of Mustache.
There are 3 types of layouts in Punch:
- Page layouts
- Section layouts
- Partial layouts
You can define a layout of its own for each page in the site. The layout for /index would be templates/index.mustache. Similarly, layout for /about/press.html would be templates/about/press.mustache.
Note that page layout must be defined in the same level as the requested page. For example, if someone requests for /about/index.html; it won't be rendered using the templates/index.mustache layout.
You will notice, on most occasions entire sections of a site carry the same layout. For example, all blog posts use a common layout. All product pages use a common layout.
Section layouts can be used to define such common layouts. A section layout must be named as _layout.mustache and must be placed inside the directory that defines the section. For example, if you define a section layout in templates/blog/_layout.mustache; it will be used to render pages such as /blog/2012-09-10-sample-post and /blog/2012/09/10-sample-post.
Section layouts are inherited. For a page request such as /blog/2012/09/10-sample-post we don't have a explicit page layout or a section layout defined for the level. However, it will use the closest section layout it can find in its ancestors; which would be templates/blog/_layout.mustache.
The templates/_layout.mustache is the top-most section layout that can be defined and it's considered as the main layout of the site. If all pages in your site uses a common layout, you can define only the templates/_layout.mustache. Then, every page will be rendered using this layout.
You can extract the parts that are repeated in multiple layouts into partials. Partial layout names must start with an underscore (eg. _header.mustache). You can render a partial layout inside a page or section layout using the following syntax.
{{> header}}
Similar to section layouts, partial layouts can also be inherited.
For some request formats, you need to present a different output than the default. For example, if you define a layout named templates/_layout.rss.mustache, it will be used to serve requests expecting a response in RSS format.
In Punch, assets such as JS, CSS and images must also be placed inside the templates directory. However, within the templates directory, you can organize them in any way you want. Punch can also pre-process and bundle the assets for you.