05. Template Elements

Template Elements are essentially equivalent to custom controls/components in JavaScript frameworks like Angular and React. They allow you to remove duplicate code from any file (page or another template) by replacing it with a custom tag like <mycustomelement/>.

Templates also support properties <mycustomelement myproperty="myvalue"/> where the value myvalue can be inserted into the Template Element's HTML code. You can also pass variables into property values for example, in the Page.html file the variable @Page.PageTitle; is valid so you can use <mycustomelement title="@Page.PageTitle;"/>.

In addition they support child content, e.g. <mycustomelement><p>Hello World</p></mycustomelement>.

Template Elements work in both HTML and Markdown pages, with the same syntax.

Template Folder

The Template folder is where you define your Template Elements. Each .html file in this folder represents a Template Element with the exception of Page.html which provides the main content of the page.

To create a new Template Element, first create a new .html file in this folder.

Template Tag Name

Important: Template tag names should always be lowercase.

When creating a Template Element you need to give it a lowercase tag name. For example, you might want to define an element <card/>, where the tag name is just card. To do this you need to put a TName tag at the start of the template file and specify the name within a name property:

<TName name="card"/>

If you do not include this tag, then you can still use the Template Element, but the tag name defaults to the file name (without file extension, and URL encoded).

The lowercase requirement is a limitation of the HTML Agility Pack which is used for parsing HTML, but it may be fixable. If you wish to remove this restriction consider opening a PR.

Template Properties

If you want your Template Element to depend on an input, then you'll need to use properties. For example, consider the following:

<mycustomelement myproperty="myvalue"/>

This can be defined by adding a TProperty tag to the start of your template .html file. The TProperty tag itself has a property name to accept the name of the property your Template Element uses. For example to achieve the code above you would add the following line to the template file:

<TProperty name="myproperty"/>

To actually use the input within the HTML file, use the text @Template.myproperty; (remember the ;!) where myproperty is replaced by the name of your property. This text will be replaced by the input you provide, so you can use it between HTML tags, within other HTML tag properties, in embeded CSS, or in embeded JavaScript.

Default Property Values

If you use the code above, but no property value is provided then @Template.myproperty; will be removed (replaced with empty string) when the template is 'rendered'. If instead you want it to be replaced with some other default value like thie string "none" then you can specify the default value in the TProperty tag like this:

<TProperty name="myproperty" default="none"/>

Child Content

Template Elements can accept child content. For example, <card><p>Hello World</p></card> will inject <p>Hello World</p> into the template. Specifically this <p>Hello World</p> will replace any instance of @ChildContent; in the template's HTML file.

Note: In Markdown files, child content can also be markdown code.

Template Element Examples

Combining everything above, suppose we have a Template Element defined by the following HTML file:

<TName name="card"/>
<TProperty name="heading"/>
<TProperty name="color" default="#fff"/>

<div class="card" style="background-color: @Template.color;">
    <h2>@Template.heading;</h2>
    @ChildContent;
</div>

Then the following code (within a page or another template):

<card/>
<card heading="My Heading"/>
<card heading="My Heading" color="#000"/>
<card heading="My Heading"><p>Lorem ipsum ...</p></card>

Would give the output:

<div class="card" style="background-color: #fff">
    <h2></h2>
</div>
<div class="card" style="background-color: #fff">
    <h2>My Heading</h2>
</div>
<div class="card" style="background-color: #000">
    <h2>My Heading</h2>
</div>
<div class="card" style="background-color: #fff">
    <h2>My Heading</h2>
    <p>Lorem ipsum ...</p>
</div>

As you can see this makes your code much neater.