@semantic-ui/templating

@semantic-ui/templating

Semantic UI provides a templating language for specifying structured html that is tightly coupled with the reactivity framework provided by the Reactive library.

This package specifically deals with compiling static html templates to an abstract syntax tree (AST) which can be parsed by a renderer like the one included for Lit in the component package.

• Basic Features
  • If/else/elseif
  • Expressions
  • Each
  • Subtemplates
  • Escaping HTML

Basic Features

If/else/elseif

You can specify conditions using {{#if condition}} blocks which can include arbitrary amount of {{elseif condition blocks as well as an {{else}}

{{#if condition}}
  <div>If block content</div>
{{elseif anotherCondition}}
  <div>ElseIf block content</div>
{{else}}
  <div>Else block content</div>
{{/if}}

Expressions

Expressions are evaluated in the data context of the template from right to left passing values along. You can use `.' to access deeply nested values

dataContext = {
  values: {
     first: false,
     second: true,
  },
  returnOpposite(value) => !value,
}

{{#if values.first}}
  Not reached
{{elseif returnOpposite values.second}}
  Not Reached
{{elseif values.second
  Reached
{{/if}}

Each

You can specify each blocks either to pass the iterated value as a variable or as the new data scope

dataContext = {
  category: 'Icecream',
  items: [
    { name: 'One' },
    { name: 'Two' },
    { name: 'Three' },
  ],
}

Adds properties to data context

<ul>
{{#each items}}
  <li>{{category}} {{name}}</li>
{{/each}}
</ul>

As new variable in context

<ul>
{{#each item in  items}}
  <li>{{category}} {{item.name}}</li>
{{/each}}
</ul>

Subtemplates

You can specify subtemplates using several syntax depending on your use case. Remember data values can either be literal values or references to expressions which are evaluated at run time.

Passing in new data context removing outer context

{{> templateName fruit='apple' toy=getFavoriteToy}}

You can also use a more complex structure, which allows you to choose a template name dynamically and specify which data should be reactive or non-reactive. Remember pushing reactive data to subtemplates can be very expensive for performance.

{{>template
  name=getTemplateName
  reactiveData={
    name=getName
  }
  data={
    fruit: 'apple',
    toy: getFavoriteToy
  }
}}

Escaping HTML

You can use {{{ triple brackets to pass in raw html.

context = {
  name: 'Dwayne <b>The Rock</b> Johnson'
}

{{{name}}}

Keep in mind values here can cause XSS vulnerabilities. A common way to mitigate this is to create a global helper to sanitize your html input if it comes from a user. There are many third party libraries that can help with this, but they are typically fairly large and are not included with templating.

import escapeHTML from 'some/npm/library';
context = {
  escapeHTML(html) {
    return escapeHTML(html);
  }
}

{{{escapeHTML name}}}

Helper Functions

Templating includes a small list of global helpers by default designed to perform basic utilities for manipulating data.

You can also register custom global helpers to run across any expression. The syntax for registering a global helper is implemented by the renderer which is included in the component class.

Helpers are called only if there is not a matching expression in the current data context.

{{#if not fruit}}
  <p class="{{activeIf user.isActive}}">{{capitalize user.name}}</p>
  <p>{{formatDate user.lastLogin 'YYYY-MM-DD'}}</p>
{{else if is fruit 'apple'}}
  You chose apple
{{/if}}

Logical Helpers

• is: Checks equality (==) between two values.
• not: Returns the logical negation (!) of a value.
• isEqual: Checks strict equality (===) between two values.
• isNotEqual: Checks for inequality (!=) between two values.
• isExactlyEqual: Checks strict equality (===) between two values.
• isNotExactlyEqual: Checks strict inequality (!==) between two values.
• greaterThan: Checks if one value is greater than another (>).
• lessThan: Checks if one value is less than another (<).
• greaterThanEquals: Checks if a value is greater than or equal to another (>=).
• lessThanEquals: Checks if a value is less than or equal to another (<=).

Format Helpers

• formatDate: Formats a date according to a given format string.
• formatDateTime: Formats a date and time according to a given format string.
• formatDateTimeSeconds: Formats a date and time with seconds according to a given format string.

String Helpers

• capitalize: "this sentence" to "This sentence"
• titleCase: "this sentence" to "This Sencence"

Conditional Class Helpers

• maybe: Returns one class if a condition is true, and another if false.
• activeIf: Returns the class 'active' if a condition is true.
• selectedIf: Returns the class 'selected' if a condition is true.
• disabledIf: Returns the class 'disabled' if a condition is true.
• checkedIf: Returns the class 'checked' if a condition is true.

Miscellaneous Helpers

• maybePlural: Adds an 's' to make a word plural based on the given value.
• numberFromIndex: Returns the number that is one greater than the given index (for 1-based counting).
• object: Returns the given object.
• log: Logs arguments to the console.
• debugger: Triggers a breakpoint in the debugger.

These helpers can be used within expressions in the template to dynamically change content based on the data context. For example: