https://github.com/ahmadnassri/node-template-literals-engine
a very simple template engine for template literals
https://github.com/ahmadnassri/node-template-literals-engine
lib literals node template
Last synced: 9 months ago
JSON representation
a very simple template engine for template literals
- Host: GitHub
- URL: https://github.com/ahmadnassri/node-template-literals-engine
- Owner: ahmadnassri
- License: mit
- Created: 2020-10-24T18:58:49.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-01-07T20:54:17.000Z (about 1 year ago)
- Last Synced: 2025-03-25T18:54:01.829Z (10 months ago)
- Topics: lib, literals, node, template
- Language: JavaScript
- Homepage:
- Size: 365 KB
- Stars: 7
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# JS Template Literals Engine
a very basic, and straight to the point Template Engine using JS Template Literals
[![license][license-img]][license-url]
[![release][release-img]][release-url]
[![semantic][semantic-img]][semantic-url]
## Why
[Template Literals][] *(also known as "Template strings")* are a familiar and simple to use method to run embedded expressions and string interpolation, which are the primary functionality of a Template Engine.
This library wraps template literals with traditional techniques *(layouts, partials, helpers, etc ...)* to facilitates the usage through a structured file format (`.jstl`)
## What
Features:
- Layouts: native support for layouts
- Partials Support: include files and pass data with ease
- Fast: Templates are cached by default
- Extensible: extensible with custom helpers
## How
### Usage
###### `template.jstl`
``` text
hello ${data.name}
```
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine(options)
engine.render('template', { name: 'ahmad' })
```
#### String Interpolation
since templates are parsed as standard JavaScript [Template Literals][] the same functionality is expected
Variables are accessible `data` context
Example
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine()
const result = engine.render('template', { name: 'ahmad' })
console.log(result)
```
###### `template.jstl`
``` text
Hello ${data.name}
```
###### result
``` bash
$ node index.js
Hello ahmad
```
#### Helper functions
Helpers are essentially functions that can be called within the template.
All helper functions are available through the `fn` context
Example
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine({
helpers: {
capitalize : str => string[0].toUpperCase() + string.slice(1)
}
})
const result = engine.render('template', { name: 'ahmad' })
console.log(result)
```
###### `template.jstl`
``` text
Hello ${fn.capitalize(data.name)}
```
###### result
``` bash
$ node index.js
Hello Ahmad
```
#### Built-in Helpers
##### `fn.render(templateName, [dataObject])`
Behaves exactly like `Engine.render` by including other template file: `templateName` inline
##### `fn.apply(templateName, [dataArray])`
enumerates over `dataArray` and applies each item to a newly rendered instance of `templateName`
Example
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine()
const actors = [
{ name: 'William Hartnell', year: '1963' },
{ name: 'Patrick Troughton', year: '1966' },
{ name: 'Jon Pertwee', year: '1970' },
{ name: 'Tom Baker', year: '1974' },
{ name: 'Peter Davison', year: '1981' },
{ name: 'Colin Baker', year: '1984' },
{ name: 'Sylvester McCoy', year: '1987' },
{ name: 'Paul McGann', year: '1996' },
{ name: 'Christopher Eccleston', year: '2005' },
{ name: 'David Tennant', year: '2005' },
{ name: 'Matt Smith', year: '2010' },
{ name: 'Peter Capaldi', year: '2013' },
{ name: 'Jodie Whittaker', year: '2017' }
]
const result = engine.render('page', { actors })
console.log(result)
```
###### `page.jstl`
``` text
${ fn.include('header') }
List of actors who have played the Doctor
${ fn.apply('doctor', data.actors) }
${ fn.include('footer') }
```
##### `doctor.jstl`
``` text
```
###### result
``` text
$ node index.js
List of actors who have played the Doctor
- William Hartnell - first appeared in 1963
- Patrick Troughton - first appeared in 1966
- Jon Pertwee - first appeared in 1970
- Tom Baker - first appeared in 1974
- Peter Davison - first appeared in 1981
- Colin Baker - first appeared in 1984
- Sylvester McCoy - first appeared in 1987
- Paul McGann - first appeared in 1996
- Christopher Eccleston - first appeared in 2005
- David Tennant - first appeared in 2005
- Matt Smith - first appeared in 2010
- Peter Capaldi - first appeared in 2013
- Jodie Whittaker - first appeared in 2017
```
#### Front Matter
Every template file can optionally include a front matter block, which is parsed and included into the `data` context
Example
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine()
const result = engine.render('template')
console.log(result)
```
###### `template.jstl`
``` text
---
name: ahmad
---
Hello ${data.name}
```
###### result
``` bash
$ node index.js
Hello ahmad
```
#### Layouts
defining a `layout` property in the Front Matter block of a template will result in rendering that layout first and including the current template as content.
Layouts can infinitely cascade, the only limit is your system resources!
Example
###### `index.js`
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine()
const result = engine.render('template', { name: 'ahmad' })
console.log(result)
```
###### `template.jstl`
``` text
---
layout: layouts/welcome
---
${data.name}
```
###### `layouts/welcome.jstl`
``` text
---
layout: layouts/base
---
Welcome!
${data.content}
```
###### `layouts/base.jstl`
``` text
${data.content}
```
###### result
``` text
$ node index.js
Welcome
ahmad
```
## API
#### Constructor `new Engine([optionsObject])`
returns a new instance of the template engine class
| name | type | required | default | description |
|-----------------|----------|----------|-----------------|----------------------------------------------------|
| **`root`** | `String` | ✖ | `process.cwd()` | path to look for template files |
| **`extension`** | `String` | ✖ | `jstl` | template file extension |
| **`helpers `** | `Object` | ✖ | `{}` | `key => function` helpers map to pass to templates |
| **`matter `** | `Object` | ✖ | `{}` | [Options][] to pass to [`gray-matter`][] |
###### example:
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine({
root: 'templates',
extension: 'html'
helpers: {
capitalize : str => string[0].toUpperCase() + string.slice(1),
...
}
})
```
#### Method: `render(templateName, [dataObject])`
parses the content of the file at `${templateName}.jstl` and passes `dataObject` to it, returns the processed output string
###### example:
``` js
const Engine = require('@ahmadnassri/template-literals-engine')
const engine = new Engine({ root: 'templates' })
engine.render('a-template') // => ./templates/a-template.jstl
engine.render('nested/template', { foo: 'bar' }) // => ./templates/nested/template.jstl
```
[Template Literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
[Options]: https://github.com/jonschlinkert/gray-matter#options
[`gray-matter`]: https://github.com/jonschlinkert/gray-matter
----
> Author: [Ahmad Nassri](https://www.ahmadnassri.com/) •
> Twitter: [@AhmadNassri](https://twitter.com/AhmadNassri)
[license-url]: LICENSE
[license-img]: https://badgen.net/github/license/ahmadnassri/node-template-literals-engine
[release-url]: https://github.com/ahmadnassri/node-template-literals-engine/releases
[release-img]: https://badgen.net/github/release/ahmadnassri/node-template-literals-engine
[semantic-url]: https://github.com/ahmadnassri/node-template-literals-engine/actions?query=workflow%3Arelease
[semantic-img]: https://badgen.net/badge/📦/semantically%20released/blue