Templates

• Overview
• How It Works
• Template Logic
• Nested Templates
• Template Types
• HTML Templates
• CSS Templates
• JavaScript (Js) Templates
• JCON Templates
• Litemark (Lite) Templates
• Text Templates

Overview 

THT introduces template functions, which let you embed HTML and other content within your scripts.

In PHP, it is common to use a third-party template language (e.g. Twig) to keep your front-end code separated from the rest.

Instead, THT supports templates directly, which has some advantages over using a 3rd party language:

• Use the standard THT syntax (e.g. 'if', 'foreach') instead of a limited, bespoke syntax.
• Call standard THT functions instead of creating “helpers”. However, calls to back-end modules (Db, File, System) are not allowed when inside a template.
• Organize templates however you want (by module, component class, etc.) instead of one template per file.
• Templates are pre-compiled to PHP code, for performance.
• Secure escaping of variables is the default behavior.

How It Works 

Templates look and act just like functions, but use the template keyword (or the T shortcut).

The type of template (e.g. 'html') is indicated in the name of the template.

The body of a template is a freeform multiline string.

When the template function is called, the body is transformed according to its type and then returned as a TypeString, which can then be passed to your output.

Whitespace and extra indentation is trimmed so you can indent however you wish.

Response.sendPage({
    title: 'My Website',
    body: pageHtml()
});

// An HTML template
template pageHtml() {

    <h1>My Website</h1>
    <p>Welcome to my site!</p>

}

Template Logic 

There are two ways to include THT logic in a template.

Expressions {{ ... }}

THT expressions can be embedded with double-curly braces.

The result is automatically escaped according to the type of template.

// (You can use `T` as a shortcut for `template`)
T pageHtml($userName) {

    <h1>My Website</h1>
    <p>Hello, {{ $userName.upperCase() }}!</p>

}

Code Lines --

Lines starting with the Code Line operator -- will be evaluated as inline THT.

Code lines must end in a semicolon or curly brace. If you need a larger block of logic, you should probably put it in a separate function.

T userListHtml($users) {

    -- $numUsers = $users.length();

    -- if !$numUsers {
        <p>No users here!</p>
    -- } else {
        <p>There are {{ $numUsers }} users:</p>
        <ul>
        -- foreach $users as $user {
            <li>{{ $user }}</li>
        -- }
        </ul>
    -- }
}

Nested Templates 

The output of other templates are included as-is (without escaping) if the template types are the same.

In this way, you can use smaller templates as “partials”.

// a single post link
T postLinkHtml($post) {
    <a href={{ $post.url }}>{{ $post.title }}</a>
}

// a list of post links
T allPostsHtml($posts) {

    <h1>Posts</h1>
    <ul>
    -- foreach $posts as $p {
        <li>{{ postLinkHtml($p) }}</li>
    -- }
    </ul>

}

Template Types 

The name of your template must end in a suffix that tells THT how it should process the content.

Supported types are:

• Html
• Js
• Css
• Lite
• Jcon
• Text

HTML Templates 

See HTML-C shortcuts for quicker ways to write HTML in your templates.

Extra whitespace inside of multiline tags is automatically trimmed so you can indent your tags without affecting the output with stray spaces.

See also: Format Checker rules for HTML templates.

// An HTML template
template pageHtml() {

    <h1>My Website</h1>
    <p>Welcome to my site!</p>

}

CSS Templates 

THT expressions within CSS should only be used as property values.

Characters like ; and { } will be removed.

T siteCss($brandColor) {

    header {
        background-color: {{ $brandColor }};
    }

}

When a CSS TypeString is included in an HTML template, it will wrap the content in a <style> block.

See the Css module for stylesheet helpers.

JavaScript (Js) Templates 

THT expressions within a Js template are converted to JavaScript data values.

It handles Strings, Booleans, Numbers. Maps & Lists are converted to JSON.

When a Js TypeString is included in an HTML template, it will wrap the content in a <script> block and a self-executing function.

// In THT...
mainJs('Tim Plate');

T mainJs($userName) {
    var userName = {{ $userName }};
}

// When included in an HTML template, it looks like this:
<script>
(function(){
    var userName = "Tim Plate";
})();
</script>

JCON Templates 

Jcon templates can be used to define hardcoded data using JCON syntax. It returns a Map or List instead of a TypeString.

THT expressions or logic are not supported in this type of template.

$data = dataJcon();
print($data.myKey[1]);  //= 'list item 1'

T dataJcon() {
    {
        myKey: [
            list item 0
            list item 1
        ]

        myOtherKey: true
    }
}

Litemark (Lite) Templates 

Lite templates support embedded Litemark content for writing page content, documentation, etc.

T mainLite() {

    # Heading

    Lorem ipsum thtum.

    - List Item 1
    - List Item 2
}

Text Templates 

Text templates do not transform or escape the content.

They return a plain string instead of a TypeString.

T emailText($name) {

     Hello {{ $name }},

     Thanks for joining our app!

     - The Team
}