Basic templates knowledge

This article is a translation of article in russian.

Files

Templates files can be found under tpl/ folder inside one of subfolders. Most of files and folders here cannot be deleted or renamed since it is not needed. Only layout templates under tpl/layouts/ folder can be created, deleted and renamed, but default layout default.tpl .

Template types

There are following types of templates with respect to its role:

• layouts — page layout
• pages — actual content of different type of pages
• widgets — widgets

Syntax

Templates code is similar to HTML, but closer to XHTML. Here are listed key features of templates in comparison to HTML:

1. HTML elements and attributes must be in lower case. <div> is correct, but <Div> or <DIV> is wrong. Upper case are used for Components (see below).
2. Block elements must be strictly closed with respect to opening tag: <div><p>...</p></div> is correct, but <div><p>...</div> or <div>...(end of file) is wrong.
3. Single elements must end with "/" before ">"like in XML. <img src="..." /> and <br/> is correct, but <img src=""> and <br> is wrong.
4. Attributes value can be enclosed with quotes or apostrophes, or can be unquoted bare-word (the last is not recommended). Also an expressions in curly braces can be used (see below).
5. Boolean attributes (like disabled or checked) can omit a value like in HTML: <input disabled/>.
6. Whitespaces in text flow at line start and end are ignored. Empty lines are ignored. See details below.
7. Text flow must not contain characters < > { } , since they have special meaning. To insert characters < and > corresponding entities &lt; and &gt;. <p>x < y</p> is wrong. <p>x &lt; y</p> is correct. To insert characters { and } you can use entities &#3C; and &#3E; or expressions with string literals (see below). Notice, that JS and CSS code should be attached with expernal files.

Notice: boolean attributes can be passed like following:

{# here attribute disabled will receive true #}
<input type="text" disabled/>
<input type="text" disabled={true}/>

{# here attribute checked will receive false,
   which can be useful for Components properties #}
<input type="checkbox" checked={false}/>

{# here attribute checked will receive a value of external parameter foobar #}
<input type="checkbox" checked={foobar}/>

Comments

Comments in templates can be places in text flow only. The syntax is following:

{# comment #}

{# commented code block
<div>
  ...
</div>
#}

Comments cannot be nested.

Ignoring whitespaces in text

Whitespaces in text flow at lines start and end are ignored with new-line characters. This allows you to wrap code in multiple lines without worriing about trash in the resulting page:

<div>
  <h1>Header</h1>
  <p>
    Lorem ipsum dolor sit
    amet consectepture adipisicing elit.
  </p>
</div>

this code will output to a page:

<div><h1>Header</h1><p>Lorem ipsum dolor sitamet consectepture adipisicing elit.</p></div>

Notice, that wrapped text is merged without spaces. When you really want that space, you can do like so:

<p>
  Lorem ipsum dolor
  {} sit amet consectepture.
</p>
<p>
  {} {}
</p>

this code will output:

<p>Lorem ipsum dolor sit amet consectepture.</p><p> </p>

Expressions

Expressions can be used for attributes values and in text. Examples:

<h1>{ title }</h1>

<a href={ url } title={ title }>...</a>

In most cases an external parameters are used in expressions. More details about expressions will be given in separate article.

Components

Components are special elements (tags), which perform some actions or output different code to page when used in template. Components in template code looks similar to usual HTML elements. Components like HTML elements can receive attributes (properties) and can be either block or single.

Notice, that components names are case sensitive. This means for example, that component CSS will not work by name <css/> or <Css/>. It will work only by <CSS/>.

Example:

{# link theme file css/styles.css to page #}
<CSS href="styles.css"/>

{# custom menu for language variants #}
<UH-Languages-Menu>
    <a
        href={url}
        class={ "nav-link ${ active && "active" }"}
    >
        {label}
    </a>
</UH-Languages-Menu>

More details about available components can be found in separate article.