Template engine module
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
api
conf
core
gradle/wrapper
handlebars
it-test
.editorconfig
.gitignore
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
RELEASING.md
build.gradle
gradle.properties
gradlew
gradlew.bat
release.gradle
settings.gradle

README.md

Knotx Template Engine Knot

Knotx Template Engine is module responsible for processing template and the data using chosen template engine strategy.

How does it work?

Template Engine filters Fragments containing te in the knots attribute. Then for each Fragment it merges Fragment Content (snippet) with data from Fragment Context (for example data from external services or form submission response) using chosen template engine strategy.

Please note that example below uses Handlebars to process the markup. Read more about it below.

Fragment Content

<knotx:snippet knots="databridge,te"
        databridge-name="books"
        type="text/knotx-snippet">
  <div class="col-md-4">
    <h2>{{_result.title}}</h2>
    <p>{{_result.synopsis.short}}</p>
    <div>Success! Status code: {{_response.statusCode}}</div>
  </div>
</knotx:snippet>

Fragment Context

{
  "_result": {
    "title":"Knot.x in Action",
    "synopsis": {
      "short": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel enim ac augue egestas rutrum non eget libero."
    }
  },
  "_response": {
    "statusCode":"200"
  }
}

Template Engine Knot uses data from Fragment Context and applies it to Fragment Content:

<div class="col-md-4">
  <h2>Knot.x in Action</h2>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel enim ac augue egestas rutrum non eget libero.</p>
  <div>Success! Status code: 200</div>
</div>

Finally Fragment Content is replaced with merged result.

Template Engine Strategy

Each snippet can specify one template engine strategy by defining te-strategy attribute in the snippet e.g.:

<knotx:snippet knots="te"
               te-strategy="acme"
               type="text/knotx-snippet">
  Some markup that te strategy can process...
</knotx:snippet>

Template Engine configuration enables to define defaultEngine that will be applied to each snippet when no te-strategy is defined.

Configuration

See the configuration docs.

Example configuration is available in the conf section of this module.

Handlebars TE Strategy

This section describes Handlebars template engine strategy that is default implementation of the template engine used in Knot.x examples. It uses Handlebars Java port to compile and evaluate templates.

Configuration

Interpolation symbol

By default, the Handlebars engine uses {{ and }} symbols as tag delimiters. However, while Knot.x can be used to generate markup on the server side, the very same page might also contain templates intended for client-side processing. This is often the case when frameworks like Angular.js or Vue.js are used. To avoid conflicts between Mustache templates to be executed server-side and ones evaluated on the client side, a Knot.x Handlebars TE introduces two configuration parameters that enable you to configure custom symbols to be used in Knot.x snippets.

E.g.: In order to use different symbols as below

<div class="col-md-4">
  <h2>Snippet1 - {<_result.message>}</h2>
</div>

You can reconfigure an engine as follows in the handlebars engine entry section:

  {
    name = handlebars
    config = {
      cacheSize = 1000
      startDelimiter = "{["
      endDelimiter = "]}"
    }
  }

How to configure?

For all configuration fields and their defaults consult HandlebarsEngineOptions

Extending handlebars with custom helpers

If the list of available handlebars helpers is not enough, you can easily extend it. To do this the following actions should be undertaken:

  1. Use io.knotx:knotx-template-engine-handlebars module as dependency
  2. Create a class implementing io.knotx.te.handlebars.CustomHandlebarsHelper interface. This interface extends com.github.jknack.handlebars.Helper
  3. Register the implementation as a service in the JAR file containing the implementation
    • Create a configuration file called META-INF/services/io.knotx.te.handlebars.CustomHandlebarsHelper in the same project as your implementation class
    • Paste a fully qualified name of the implementation class inside the configuration file. If you're providing multiple helpers in a single JAR, you can list them in new lines (one name per line is allowed)
    • Make sure the configuration file is part of the JAR file containing the implementation class(es)
  4. Run Knot.x with the JAR file in the classpath

Example extension

See acme-handlebars-ext in the knotx-example-project.

This module contains an example custom Handlebars helper - BoldHelper.

How to create custom Template Engine strategy?

All you need to do is simply implement 2 interfaces from the knotx-template-engine-api:

and declare META-INF/services/io.knotx.te.api.TemplateEngineFactory on the classpath with your TemplateEngineFactory implementation.

handlebars module in this repo is an example of such implementation. You can find another example example in the Knot.x example project - acme te.