https://github.com/ryanmorr/templar
A simple and versatile DOM templating engine
https://github.com/ryanmorr/templar
dom javascript template ui
Last synced: about 1 year ago
JSON representation
A simple and versatile DOM templating engine
- Host: GitHub
- URL: https://github.com/ryanmorr/templar
- Owner: ryanmorr
- License: unlicense
- Created: 2016-10-06T19:47:25.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-01-19T19:12:48.000Z (over 2 years ago)
- Last Synced: 2024-04-14T13:07:30.905Z (about 2 years ago)
- Topics: dom, javascript, template, ui
- Language: JavaScript
- Homepage:
- Size: 1.32 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# templar
[![Version Badge][version-image]][project-url]
[![License][license-image]][license-url]
[![Build Status][build-image]][build-url]
> A simple and versatile DOM templating engine
## Install
Download the [CJS](https://github.com/ryanmorr/templar/raw/master/dist/cjs/templar.js), [ESM](https://github.com/ryanmorr/templar/raw/master/dist/esm/templar.js), [UMD](https://github.com/ryanmorr/templar/raw/master/dist/umd/templar.js) versions or install via NPM:
``` sh
npm install @ryanmorr/templar
```
## Usage
Template syntax is similar to your standard mustache templates with double curly braces (`{{` `}}`) serving as delimiters to internal logic. The tokens found between the delimiters are the reference point for the value of its place in the template:
```javascript
import templar from '@ryanmorr/templar';
// Create a new template
const tpl = templar('
{{content}}');
// Set the id and content
tpl.set('id', 'foo');
tpl.set('content', 'bar');
// Append to the DOM
tpl.mount(document.body);
```
## API
### `templar(tpl, data?)`
Create a new template by providing a template string and optionally provide a data object to set default values:
```javascript
const tpl = templar('
{{bar}}', {
foo: 'abc',
bar: 123
});
```
------
### `set(token, value?)`
Set the value of a token and trigger the template to dynamically update with the new value. You can also provide an object literal to set multiple tokens at once:
```javascript
const tpl = templar('
{{bar}} {{baz}}');
// Set a single value
tpl.set('foo', 'aaa');
// Set multiple values
tpl.set({
bar: 'bbb',
baz: 'ccc'
});
```
Supports basic interpolation with strings and numbers:
```javascript
const tpl = templar('
{{bar}}');
tpl.set('foo', 'aaa');
tpl.set('bar', 123);
```
DOM nodes are also supported, including text nodes, elements, document fragments, and HTML strings:
```javascript
const tpl = templar('
{{foo}} {{bar}} {{baz}}');
tpl.set('foo', document.createElement('div'));
tpl.set('bar', document.createDocumentFragment());
tpl.set('baz', 'bold');
```
Set CSS styles as a string or object:
```javascript
const tpl = templar('
');
tpl.set('style', 'width: 10px; height: 10px');
tpl.set('style', {width: '20px', height: '20px'});
```
Add and remove event listeners:
```javascript
const tpl = templar('Click Me!');
tpl.set('onClick', (e) => {
// Handle the click event
});
```
You can even nest templates within templates:
```javascript
const div = templar('
{{content}}');
const em = templar('{{text}}');
div.set('foo', em);
em.set('text', 'some text');
```
By default, HTML strings are automatically parsed into DOM nodes. To prevent this and escape HTML characters instead, prefix a token with an ampersand (&):
```javascript
const tpl = templar('
{{&foo}}');
tpl.set('foo', 'foo'); //=> <i>foo</i>
```
------
### `get(token)`
Get the current value of a token:
```javascript
const tpl = templar('
', {foo: 123});
tpl.get('foo'); //=> 123
```
------
### `mount(parent)`
Append the template to an element:
```javascript
const tpl = templar('
{{foo}}');
tpl.mount(document.body);
```
------
### `unmount()`
Remove the template from its parent element:
```javascript
const tpl = templar('
{{foo}}');
tpl.mount(document.body);
tpl.unmount();
```
------
### `on(name, callback)`
Subcribe a callback function to a custom event (mount, unmount, change, attributechange). Returns a function capable of removing the listener.
```javascript
const tpl = templar('
{{foo}}');
tpl.on('mount', (element) => {
// Executed when the template is appended to an element
});
tpl.on('unmount', () => {
// Executed when the template is removed from an element
});
tpl.on('change', (element) => {
// Executed when the contents of an element are updated
});
const off = tpl.on('attributechange', (element, oldValue, newValue) => {
// Executed when an attribute changes
off(); // Remove custom event listener
});
```
## License
This project is dedicated to the public domain as described by the [Unlicense](http://unlicense.org/).
[project-url]: https://github.com/ryanmorr/templar
[version-image]: https://img.shields.io/github/package-json/v/ryanmorr/templar?color=blue&style=flat-square
[build-url]: https://github.com/ryanmorr/templar/actions
[build-image]: https://img.shields.io/github/actions/workflow/status/ryanmorr/templar/node.js.yml?style=flat-square
[license-image]: https://img.shields.io/github/license/ryanmorr/templar?color=blue&style=flat-square
[license-url]: UNLICENSE