feelers

feelers

A templating solution built on top of DMN FEEL. Like moustache / handlebars but with FEEL.

What is inside

• A lezer grammar and consequently parser for the templating language
• A parseMixed language definition which brings feelers templating, feel parsing and an optional host language together
• An editor for feelers, build on top of codemirror
• An interpreter to fill your templates with data, powered by feelin
• A simple playground to showcase the language

Usage

Feelers is a string templating tool, and will return string text or error.

import { evaluate } from 'feelers'`

A simple string will always be returned as-is.

evaluate("My simple string");
// "My simple string"

If your string is prefixed with an =, it will be evaluated as a single FEEL expression wrapped in a string conversion function.

const context = { secondNumber: 12 };
evaluate("= 2 + secondNumber", context);
// "14"

Finally, if your string features feelers language features, the templating engine takes over.

const context = { user: "Dave" };
evaluate("I'm sorry {{user}}, I'm afraid I can't do that.", context);
// I'm sorry Dave, I'm afraid I can't do that.

Feelers templating language features

Inserts

The simplest feature of feelers is inserting FEEL evaluations within your text. You may provide a variable context for the underlying FEEL engine to reference. Within these scopes, you have access to all features of the FEEL engine.

const context = { user: "Dave", age: 24, hobbies: [ "surfing", "coding" ] };

evaluate(`Hey there {{user}}, welcome. {{if age >= 18 then "Have a beer!" else "Here's some apple juice."}}`, context);
// Hey there Dave. Have a beer!

evaluate(`Hobbies: {{hobbies}}`, context);
// Hobbies: ["surfing", "coding"]

evaluate(`{{user}}-{{user}}-{{user}}`, context);
// Dave-Dave-Dave

Conditional sections

To simply display a section of the template, you may use a conditional section. While this can already be achieved via feel itself using if then else, this syntax is a lot easier to manage for large sections.

const conditionExample = `{{#if count(users) > 1}}There are multiple users{{/if}}
{{#if false}}This should not display{{/if}}
{{#if true}}This should display{{/if}}`;

const context = { users: [ "Bob", "Dave" ] };

evaluate(conditionExample, context);
// There are multiple users
// This should display

Loops

To handle dealing with arrays of data graciously, you can make use of loop tags. A special variable this is create granting you access to the current loop's element.

const context = { user: "Dave", age: 24, hobbies: [ "surfing", "coding" ] };
const hobbyExpression = `{{user}}'s hobbies are:
{{#loop hobbies}}
- {{this}}
{{/loop}}`;

evaluate(hobbyExpression, context);
/// Dave's hobbies are:
/// - surfing
/// - coding

Loops may be nested when dealing with more complex data. When this is an object, you may access its variables directly within the loop. Although this.name would also work in the below example

const context = {
  users: [
    {
      name: "Bob",
      hobbies: [ "building", "wearing hardhats" ]
    },
    {
      name: "Dave",
      hobbies: [ "surfing", "coding" ]
    }
  ]
}

const complexLoops = `{{#loop users}}
{{name}}'s hobbies:
{{#loop hobbies}}
- {{this}}
{{/loop}}
{{/loop}}
`

evaluate(complexLoops, context);
// Bobs's hobbies:
// - building
// - wearing hardhats
// Dave's hobbies:
// - surfing
// - coding

Loops actually create 4 helper variables: this, parent, _this_ and _parent_. Parent refers to the context just outside of your loop, in case you need to refer to it. The underscored variants are fallbacks in case your context include variables named this and parent.

Build and run

Build the project in a Posix environment. On Windows, that is Git Bash or WSL.

Note we currently support development environments with Node.js version 16 (and npm version 8). We encourage you to use a Node.js version manager (e.g., nvm or n) to set up the needed versions.

Prepare the project by installing all dependencies:

npm install

Then, depending on your use-case you may run any of the following commands:

# run all tests
npm run test

# runs single-start test case for development
npm start
npm run start

# generate the lezer parser from its grammar definition
npm run generate:parser

# build all dependencies locally and spool up playground
npm run start:playground

# build all dependencies locally and build playground
npm run build:playground

Related

• lezer-feel - FEEL language definition for the Lezer parser system
• feel-playground - Interactive playground to learn the FEEL language

License

MIT