HiFi's template selection process is designed to help front-end developers avoid unnecessary redundancy while still having fine-grained control over how a site is designed.
When a visitor hits a URL on the website HiFi finds the content object in the system that corresponds to that URL. Every object in HiFi has a type (i.e. post, page, author, etc). Some types inherit from other types meaning they are special cases of another type and add additional fields to a type. This type information, as well as the URL of the content, are used in HiFi's template selection.
Required Template Directory Structure:
The directory structure of the templates does not matter for the most part. The only exception are the following folders that make up the type hierarchy and error pages:
Deciding which template to use.
HiFi decides which template to start with by using the following process. As soon as it finds a match, the looking stops. So if it finds a specific url template in step 3, then it is done.
- Finding the type field of the content it is trying to present.
- Choosing the directory to start in based on type.
- Checking for a specific URL template. (/blog/post checks /templates/page/post/url/blog/post.html first)
- Checking for a general URL template (then /templates/page/post/url/blog/index.html)
- Checking for a type specific template (then /templates/page/post/post.html)
- Checking for a type ancestor's template:
- Specific URL (/templates/page/url/blog/post.html)
- General URL (/templates/page/url/blog/index.html)
- Type (/templates/page/page.html)
- Falling back to index.html
Essentially HiFi starts looking for the most specific type and URL possible and then gradually look for less specific template matches. The template designer can thus implement only a few generic templates to have the structure of a site setup and progressively refine the site by adding more detail to certain types or certain areas of a site.
Using the template.
Once the template is selected -- it will be used by Twig. Typically you will want to extend another template, but this is not necessary. When the template loads, the only variables that will be ready is the hifi variable and 'this'. This will be populated with the object that was selected through the url.
So if you visit /blog/some-post, you'll get the post with the url '/blog/some-post' and have all of its values ready.