Basic Page Composition With Templates, Fragments And Includes
Prerequisites
Before proceeding with this tutorial, please familiarize yourself with Trio's Core Concepts.
Intention Of This Tutorial
In this tutorial we will explore Trio's basic page composition. Unlike advanced page composition, which will be the subject of the next tutorial, basic page composition centers around the use of template, fragment and include project assets to compose your HTML documents, and doesn't involve the use of any tag-based callbacks.
Our use case for this tutorial is trivial. We want Trio to generate an HTML page that contains a page header and a list containing the names of artist and their relevant information. If we were to hand code this HTML page, this is what it would look like:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Hand Coded</title>
</head>
<body>
<header>Artists Registry</header>
<main>
<h2>Artists</h2>
<ul>
<li>Terry Shannon</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Glen Miller</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Kris Jay</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Riley Webb</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Vic Christy</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Caden Ray</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Steff Hammer</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Billie Noble</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Danni Powell</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Blair Gordonlist</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
</ul>
</main>
</body>
</html>
Create A New Project
In your terminal application, run the following command (please replace "path/to/new/project" with the actual path you would prefer for the location of your new project) to create a new project:
trio new path/to/new/project
Create The Template Project Asset
In the project's source/templates folder, create a new template file named default.html and copy and paste the following markup into that file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<link rel="stylesheet" href="/css/main.4b032a8bb77734ada3ae34e1a6cf849f.css">
</head>
<body>
<header data-trio-include="header.md"></header>
<main data-trio-fragment></main>
</body>
</html>
Please notice that the above template project asset contains a single tag (in this case, a "main" tag) that is decorated with the data-trio-fragment attribute. When Trio finds such a tag decorated with this attribute in a template it will target it with any content it finds in the associated fragment. This isn't required if the fragment isn't contributing any content of its own.
Create The Fragment Project Asset
In the project's source/fragments folder, create a new fragment file named index.html and copy and paste the following into that:
<!--
template: default
title: Hard Coded In Fragment
appendToTarget: true
-->
<h2>Artists</h2>
<ul>
<li>Terry Shannon</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Glen Miller</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Kris Jay</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Riley Webb</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Vic Christy</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Caden Ray</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Steff Hammer</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Billie Noble</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Danni Powell</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Blair Gordonlist</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
</ul>
Please notice how the above fragment project asset declares front matter at the very top of the file, in which it defines:
- The required front matter property template with the name of the template file it is associated with and
- The required front matter property title with the title to be assigned to the generated document's title tag and
- The optional front matter property appendToTarget which Trio uses to determine if it should append to or replace the tag in the template that is decorated with the data-trio-fragment attribute with the fragment's content. By assigning true, Trio will append whatever content it finds in the associated fragment to this tag.
Create The Include Project Asset
In the project's source/includes folder, create a new include file named header.md and copy and paste the following into that:
<!--
appendToTarget: true
-->
# Artists Registry
Please notice how the above include project asset declares front matter at the very top of the file which defines the optional boolean front matter property appendToTarget, which Trio uses to determine if it should append to or replace the tag in the template that is decorated with the data-trio-include="header.md" attribute with the include's content. By assigning true, Trio will append whatever content it finds in the fragment to this tag.
Build And Run The Project
Now that we have composed our intended page using a template and a fragment and an include, we are ready to build our site and render the page in the browser. In your terminal application, please run the following commands from the root folder of your project:
trio build; trio serve
If you prefer, you can use the abbreviated forms of these commands instead:
trio b; trio s
The build command instructs Trio to do a one-off build of your site for development and to place the site's generated output into the project's public/ folder. The serve command instructs Trio to serve the project's public/ folder's content in the browser.
When rendered in the browser the page that you created, public/index.html, should look like the following:
You can also view the content of the generated HTML document, which resides in public/index.html, by simply opening it in your editor of choice or by running cat public/index.html from the root of your project in the terminal. Let's take a look at it now:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Hard Coded In Fragment</title>
<link rel="stylesheet" href="/css/main.4b032a8bb77734ada3ae34e1a6cf849f.css">
</head>
<body>
<header data-trio-include="header.md">
<h1 id="artists-registry">Artists Registry</h1>
</header>
<main data-trio-fragment>
<h2>Artists</h2>
<ul>
<li>Terry Shannon</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Glen Miller</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Kris Jay</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Riley Webb</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Vic Christy</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Caden Ray</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Steff Hammer</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Billie Noble</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
<li>Danni Powell</li>
<ul>
<li>Medium: Watercolor</li>
<li>Style: Impressionism</li>
</ul>
<li>Blair Gordonlist</li>
<ul>
<li>Medium: Oil</li>
<li>Style: Impressionism</li>
</ul>
</ul>
</main>
</body>
</html>
From the above we can see that Trio in fact did as we had requested it to do by appending the fragment's content to the template's main tag that was decorated with the data-trio-fragment attribute and by appending the include's content to the template's header tag that was decorated with the data-trio-include="header.md" attribute.
Also note that because we built the project for development using Trio's build command, Trio preserved all the data-trio-* attributes. If we had instead built the project using Trio's release command, which is used to build your project prior to its release, Trio would have removed all the data-trio-* attributes from the generated pages.
Extra Credit
Generate the site again but this time either remove the appendToTarget front matter property from the fragment's front matter or set it's value to false. Now view the generated index.html file in your project's public/ folder. Can you spot the difference in the generated output?
Takeaways From This Tutorial
- Trio's web page generation process is called page composition.
- Each web page that Trio generates and writes to the file system as an .html file is made from (i.e. composed from) numerous project assets.
- Until Trio actually writes the web page to the file system, it exists purely in the computer's memory and is referred to as a composite.
- At a minimum, every web page that Trio creates must be composed from a single template project asset, and a single fragment project asset, both of which can optionally include one or more include project assets. As this is the most basic form of page composition that Trio provides it is called basic page composition.
- Basic page composition, unlike advanced page composition, doesn't involve any JavaScript; it only involves the content that is contributed by fragment, template, and include project assets and tags decorated with the data-trio-fragment attribute, and tags decorated with the data-trio-include attribute.
- template project assets are used to provides your web page with its general layout and structure. They may optionally also provide a target tag that Trio will apply the associated fragment's content to. They must always be an .html file and they should include the !DOCTYPE document preamble, the html, the head and the body sections typically found in an HTML document.
- fragment project assets are used to direct Trio to generate a composite from a template project asset. They must always include front matter at the very top of the file. They can optionally contribute their own content to the composite. They may be either an .html or a .md file.
- include project assets are used to add reusable blocks of content (e.g. headers, footers, etc.) to the composites created from fragment and template project assets. They can optionally include front matter at the very top of the file.
- There is a one to one relationship between a fragment project asset and a template project asset, meaning that a fragment can only be associated with a single template.
- There can be a many to one relationship between a single template and multiple fragments, meaning that multiple fragments can be associated with the same template.
Conclusion
This tutorial examined how you can use Trio's basic page composition to create your site's HTML documents. Basic page composition, while simple to grasp and implement, is limiting in that you can only compose your HTML documents with the contents of your template, fragment and include project assets - it doesn't support augmenting your composites with data you define in fragment front matter or in JSON data files.
In the next set of tutorials in this series we will examine using Trio's advanced page composition to compose your HTML documents with dynamic content found in fragment front matter and in JSON data files, along with implementing tag-based callbacks.