lessons-learned
/
fastify-riotjs-and-lowdb
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'b963b3396c'
${ noResults }
fastify-riotjs-and-lowdb/node_modules/@riotjs/dom-bindings/README.md

547 lines
16 KiB
Raw Blame History

# dom-bindings
[![Build Status][travis-image]][travis-url]
[![Code Quality][codeclimate-image]][codeclimate-url]
[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][npm-url]
[![MIT License][license-image]][license-url]
[![Coverage Status][coverage-image]][coverage-url]
## Usage
```js
import { template, expressionTypes } from '@riotjs/dom-bindings'
// Create the app template
const tmpl = template('<p><!----></p>', [{
selector: 'p',
expressions: [
{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate: scope => scope.greeting,
},
],
}])
// Mount the template to any DOM node
const target = document.getElementById('app')
const app = tmpl.mount(target, {
greeting: 'Hello World'
})
```
[travis-image]:https://img.shields.io/travis/riot/dom-bindings.svg?style=flat-square
[travis-url]:https://travis-ci.org/riot/dom-bindings
[license-image]:http://img.shields.io/badge/license-MIT-000000.svg?style=flat-square
[license-url]:LICENSE
[npm-version-image]:http://img.shields.io/npm/v/@riotjs/dom-bindings.svg?style=flat-square
[npm-downloads-image]:http://img.shields.io/npm/dm/@riotjs/dom-bindings.svg?style=flat-square
[npm-url]:https://npmjs.org/package/@riotjs/dom-bindings
[coverage-image]:https://img.shields.io/coveralls/riot/dom-bindings/master.svg?style=flat-square
[coverage-url]:https://coveralls.io/r/riot/dom-bindings/?branch=master
[codeclimate-image]:https://api.codeclimate.com/v1/badges/d0b7c555a1673354d66f/maintainability
[codeclimate-url]:https://codeclimate.com/github/riot/dom-bindings/maintainability
## API
### template(String, Array)
The template method is the most important of this package.
It will create a `TemplateChunk` that could be mounted, updated and unmounted to any DOM node.
<details>
<summary>Details</summary>
A template will always need a string as first argument and a list of `Bindings` to work properly.
Consider the following example:
```js
const tmpl = template('<p><!----></p>', [{
selector: 'p',
expressions: [
{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate: scope => scope.greeting
}
],
}])
```
The template object above will bind a [simple binding](#simple-binding) to the `<p>` tag.
</details>
### bindingTypes
Object containing all the type of bindings supported
### expressionTypes
Object containing all the expressions types supported
## Bindings
A binding is simply an object that will be used internally to map the data structure provided to a DOM tree.
<details>
<summary>Details</summary>
To create a binding object you might use the following properties:
- `expressions`
- type: `Array<Expression>`
- required: `true`
- description: array containing instructions to execute DOM manipulation on the node queried
- `type`
- type: `Number`
- default:`bindingTypes.SIMPLE`
- optional: `true`
- description: id of the binding to use on the node queried. This id must be one of the keys available in the `bindingTypes` object
- `selector`
- type: `String`
- default: binding root **HTMLElement**
- optional: `true`
- description: property to query the node element that needs to updated
The bindings supported are only of 4 different types:
- [`simple`](#simple-binding) to bind simply the expressions to a DOM structure
- [`each`](#each-binding) to render DOM lists
- [`if`](#if-binding) to handle conditional DOM structures
- [`tag`](#tag-binding) to mount a coustom tag template to any DOM node
Combining the bindings above we can map any javascript object to a DOM template.
</details>
### Simple Binding
These kind of bindings will be only used to connect the expressions to DOM nodes in order to manipulate them.
<details>
<summary>Details</summary>
**Simple bindings will never modify the DOM tree structure, they will only target a single node.**<br/>
A simple binding must always contain at least one of the following expression:
- `attribute` to update the node attributes
- `event` to set the event handling
- `text` to update the node content
- `value` to update the node value
For example, let's consider the following binding:
```js
const pGreetingBinding = {
selector: 'p',
expressions: [{
type: expressionTypes.Text,
childNodeIndex: 0,
evaluate: scope => scope.greeting,
}]
}
template('<article><p><!----></p></article>', [pGreeting])
```
In this case we have created a binding to update only the content of a `p` tag.<br/>
*Notice that the `p` tag has an empty comment that will be replaced with the value of the binding expression whenever the template will be mounted*
</details>
#### Simple Binding Expressions
The simple binding supports DOM manipulations only via expressions.
<details>
<summary>Details</summary>
An expression object must have always at least the following properties:
- `evaluate`
- type: `Function`
- description: function that will receive the current template scope and will return the current expression value
- `type`
- type: `Number`
- description: id to find the expression we need to apply to the node. This id must be one of the keys available in the `expressionTypes` object
</details>
##### Attribute Expression
The attribute expression allows to update all the DOM node attributes.
<details>
<summary>Details</summary>
This expression might contain the optional `name` key to update a single attribute for example:
```js
// update only the class attribute
{ type: expressionTypes.ATTRIBUTE, name: 'class', evaluate(scope) { return scope.attr }}
```
If the `name` key will not be defined and the return of the `evaluate` function will be an object, this expression will set all the pairs `key, value` as DOM attributes. <br/>
Given the current scope `{ attr: { class: 'hello', 'name': 'world' }}`, the following expression will allow to set all the object attributes:
```js
{ type: expressionTypes.ATTRIBUTE, evaluate(scope) { return scope.attr }}
```
If the return value of the evaluate function will be a `Boolean` the attribute will be considered a boolean attribute like `checked` or `selected`...
</details>
##### Event Expression
The event expression is really simple, It must contain the `name` attribute and it will set the callback as `dom[name] = callback`.
<details>
<summary>Details</summary>
For example:
```js
// add an event listener
{ type: expressionTypes.EVENT, name: 'onclick', evaluate(scope) { return function() { console.log('Hello There') } }}
```
To remove an event listener you should only `return null` via evaluate function:
```js
// remove an event listener
{ type: expressionTypes.EVENT, name: 'onclick', evaluate(scope) { return null } }}
```
</details>
##### Text Expression
The text expression must contain the `childNodeIndex` that will be used to identify which childNode from the `element.childNodes` collection will need to update its text content.
<details>
<summary>Details</summary>
Given for example the following template:
```html
<p><b>Your name is:</b><i>user_icon</i><!----></p>
```
we could use the following text expression to replace the CommentNode with a TextNode
```js
{ type: expressionTypes.TEXT, childNodeIndex: 2, evaluate(scope) { return 'Gianluca' } }}
```
</details>
##### Value Expression
The value expression will just set the `element.value` with the value received from the evaluate function.
<details>
<summary>Details</summary>
It should be used only for form elements and it might look like the example below:
```js
{ type: expressionTypes.VALUE, evaluate(scope) { return scope.val }}
```
</details>
### Each Binding
The `each` binding is used to create multiple DOM nodes of the same type. This binding is typically used in to render javascript collections.
<details>
<summary>Details</summary>
**`each` bindings will need a template that will be cloned, mounted and updated for all the instances of the collection.**<br/>
An each binding should contain the following properties:
- `itemName`
- type: `String`
- required: `true`
- description: name to identify the item object of the current iteration
- `indexName`
- type: `Number`
- optional: `true`
- description: name to identify the current item index
- `evaluate`
- type: `Function`
- required: `true`
- description: function that will return the collection to iterate
- `template`
- type: `TemplateChunk`
- required: `true`
- description: a dom-bindings template that will be used as skeleton for the DOM elements created
- `condition`
- type: `Function`
- optional: `true`
- description: function that can be used to filter the items from the collection
The each bindings have the highest [hierarchical priority](#bindings-hierarchy) compared to the other riot bindings.
The following binding will loop through the `scope.items` collection creating several `p` tags having as TextNode child value dependent loop item received
```js
const eachBinding = {
type: bindingTypes.EACH,
itemName: 'val',
indexName: 'index'
evaluate: scope => scope.items,
template: template('<!---->', [{
expressions: [
{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate: scope => `${scope.val} - ${scope.index}`
}
]
}
}
template('<p></p>', [eachBinding])
```
</details>
### If Binding
The `if` bindings are needed to handle conditionally entire parts of your components templates
<details>
<summary>Details</summary>
**`if` bindings will need a template that will be mounted and unmounted depending on the return value of the evaluate function.**<br/>
An if binding should contain the following properties:
- `evaluate`
- type: `Function`
- required: `true`
- description: if this function will return truthy values the template will be mounted otherwise unmounted
- `template`
- type: `TemplateChunk`
- required: `true`
- description: a dom-bindings template that will be used as skeleton for the DOM element created
The following binding will render the `b` tag only if the `scope.isVisible` property will be truthy. Otherwise the `b` tag will be removed from the template
```js
const ifBinding = {
type: bindingTypes.IF,
evaluate: scope => scope.isVisible,
selector: 'b'
template: template('<!---->', [{
expressions: [
{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate: scope => scope.name
}
]
}])
}
template('<p>Hello there <b></b></p>', [ifBinding])
```
</details>
### Tag Binding
The `tag` bindings are needed to mount custom components implementations
<details>
<summary>Details</summary>
`tag` bindings will enhance any child node with a custom component factory function. These bindings are likely riot components that must be mounted as children in a parent component template
A tag binding might contain the following properties:
- `getComponent`
- type: `Function`
- required: `true`
- description: the factory function responsible for the tag creation
- `evaluate`
- type: `Function`
- required: `true`
- description: it will receive the current scope and it must return the component id that will be passed as first argument to the `getComponent` function
- `slots`
- type: `Array<Slot>`
- optional: `true`
- description: array containing the slots that must be mounted into the child tag
- `attributes`
- type: `Array<AttributeExpression>`
- optional: `true`
- description: array containing the attribute values that should be passed to the child tag
The following tag binding will upgrade the `time` tag using the `human-readable-time` template.
This is how the `human-readable-time` template might look like
```js
import moment from 'moment'
export default function HumanReadableTime({ attributes }) {
const dateTimeAttr = attributes.find(({ name }) => name === 'datetime')
return template('<!---->', [{
expressions: [{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate(scope) {
const dateTimeValue = dateTimeAttr.evaluate(scope)
return moment(new Date(dateTimeValue)).fromNow()
}
}, ...attributes.map(attr => {
return {
...attr,
type: expressionTypes.ATTRIBUTE
}
})]
}])
}
```
Here it's how the previous tag might be used in a `tag` binding
```js
import HumanReadableTime from './human-readable-time'
const tagBinding = {
type: bindingTypes.TAG,
evaluate: () => 'human-readable-time',
getComponent: () => HumanReadableTime,
selector: 'time',
attributes: [{
evaluate: scope => scope.time,
name: 'datetime'
}]
}
template('<p>Your last commit was: <time></time></p>', [tagBinding]).mount(app, {
time: '2017-02-14'
})
```
The `tag` bindings have always a lower priority compared to the `if` and `each` bindings
</details>
#### Slot Binding
The slot binding will be used to manage nested slotted templates that will be update using parent scope
<details>
<summary>Details</summary>
An expression object must have always at least the following properties:
- `evaluate`
- type: `Function`
- description: function that will receive the current template scope and will return the current expression value
- `type`
- type: `Number`
- description: id to find the expression we need to apply to the node. This id must be one of the keys available in the `expressionTypes` object
- `name`
- type: `String`
- description: the name to identify the binding html we need to mount in this node
```js
// slots array that will be mounted receiving the scope of the parent template
const slots = [{
id: 'foo',
bindings: [{
selector: '[expr1]',
expressions: [{
type: expressionTypes.TEXT,
childNodeIndex: 0,
evaluate: scope => scope.text
}]
}],
html: '<p expr1><!----></p>'
}]
const el = template('<article><slot expr0/></article>', [{
type: bindingTypes.SLOT,
selector: '[expr0]',
name: 'foo'
}]).mount(app, {
slots
}, { text: 'hello' })
```
</details>
## Bindings Hierarchy
If the same DOM node has multiple bindings bound to it, they should be created following the order below:
1. Each Binding
2. If Binding
3. Tag Binding
<details>
<summary>Details</summary>
Let's see some cases where we might combine multiple bindings on the same DOM node and how to handle them properly.
### Each and If Bindings
Let's consider for example a DOM node that sould handle in parallel the Each and If bindings.
In that case we could skip the `If Binding` and just use the `condition` function provided by the [`Each Binding`](#each-binding)
Each bindings will handle conditional rendering internally without the need of extra logic.
### Each and Tag Bindings
A custom tag having an Each Binding bound to it should be handled giving the priority to the Eeach Binding. For example:
```js
const components = {
'my-tag': function({ slots, attributes }) {
return {
mount(el, scope) {
// do stuff on the mount
},
unmount() {
// do stuff on the unmount
}
}
}
}
const el = template('<ul><li expr0></li></ul>', [{
type: bindingTypes.EACH,
itemName: 'val',
selector: '[expr0]',
evaluate: scope => scope.items,
template: template(null, [{
type: bindingTypes.TAG,
name: 'my-tag',
getComponent(name) {
// name here will be 'my-tag'
return components[name]
}
}])
}]).mount(target, { items: [1, 2] })
```
The template for the Each Binding above will be created receiving `null` as first argument because we suppose that the custom tag template was already stored and registered somewhere else.
### If and Tag Bindings
Similar to the previous example, If Bindings have always the priority on the Tag Bindings. For example:
```js
const el = template('<ul><li expr0></li></ul>', [{
type: bindingTypes.IF,
selector: '[expr0]',
evaluate: scope => scope.isVisible,
template: template(null, [{
type: bindingTypes.TAG,
evaluate: () => 'my-tag',
getComponent(name) {
// name here will be 'my-tag'
return components[name]
}
}])
}]).mount(target, { isVisible: true })
```
The template for the IF Binding will mount/unmount the Tag Binding on its own DOM node.
</details>
Reference in new issue View Git Blame Copy Permalink