punybind

v1.2.1

Published

a year ago

A minimalist binding helper

Downloads

3,516

0High
0Medium
0Low

arnaud.buchholz

HTML binding

punybind 🦴

A minimalist (2889 bytes) one-way binding helper.

Usage

1. Include the punybind helper

<script src="https://cdn.jsdelivr.net/npm/punybind/dist/punybind.js"></script>

2. Define bindings in the HTML

<html>
  <head>
    <title>TODO list</title>
  </head>
  <body>
    <h1>{{ title }}</h1>
    <ul>
      <li
        {{for}}="item of items"
        class="todo{{ item.done ? ' done' : '' }}"
      >{{ item.text }}</li>
    </ul>
  </body>
</html>

See below for supported syntaxes.

3. Bind the section

const update = await punybind(document.body)

The update asynchronous method exposes the following properties :

bindingsCount (number) : The number of bindings detected
model (object) : The reactive model (see below)
done (function) : Returns a promise being fulfilled when the last update completes (see below).

Upon update invocation, the returned promise is fulfilled when the DOM update is completed.

4. Update the section by passing a context object

await update({
  title: 'My TODO list',
  items: [{
    done: true,
    text: 'Forget about heavy frameworks'
  }, {
    done: false,
    text: 'Adopt punybind'
  }]
})

Or use the reactive model (see below).

5. Enjoy !

Supported syntaxes

Text and attribute binding

Text nodes and attribute values leverage binding using the {{ expression }} syntax.

The expression is evaluated with the properties of the contextual object.

It is possible to mix static content with computed one but any error clears the whole value.

Iterators

Iterators allow the repetition of elements.

An iterator is declared on the element to repeat using the special attribute {{for}} with the value being either :

{{for}}="item of expression"
{{for}}="item, index of expression"

Where :

item is the contextual property receiving the value of the current iteration (to use in the subsequent bindings),
index is the contextual property receiving the index of the current iteration (0-based),
expression must evaluate to an iterable object.

Conditionals

Conditionals rule the rendering of elements.

They can form an if / elseif / else chain. Their expression must evaluate to a truthy value to enable rendering.

To work properly, the attributes must be set on contiguous sibling elements :

{{if}}="expression" : must be the first element of the chain,
{{elseif}}="expression" : (optional) is evaluated and rendered only if the previous if / elseif did not evaluate to a truthy value,
{{else}} : (optional) terminates the chain and is rendered only if the previous if / elseif did not evaluate to a truthy value.

Reactive model

const { model, done } = await punybind(document.body, {
  title: 'Hello World !',
  items: []
})
console.log(model.title) // Hello World !
// The following lines of code trigger updates
model.title = 'My TODO list'
model.items.push({
  done: false,
  text: 'Adopt punybind'
})
await done() // Wait for the DOM update to be completed

Customizing

It is possible to tweak some settings with punybind.use, for instance :

// see https://www.npmjs.com/package/punyexpr
const safebind = punybind.use({
  compiler: punyexpr
})
// safebind offers the same features as punybind
const { model, done } = await safebind(document.body, {
  title: 'Hello World !',
  items: []
})

Available options :

compiler: (expression: string) => (context: object) => any
- Function that compiles the expression and return a function that evaluates it with the given context. Default compiler uses an eval-like syntax.

Implementation notes

The default expression compiler implementation is not compliant with Content Security Policy.
Only properties coming from the contextual object can be used in evaluated expressions.
Bound elements are hidden under template elements.
When any error occurs (inconsistent binding, invalid syntax), the binding silently fails.