128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# @thefarce/loom
|
|
|
|
## What is this?
|
|
|
|
Loom is a tool for weaving form data with content data in nodejs. It does
|
|
this by using elements of the Unified.js toolkit for parsing text into
|
|
abstract syntax trees (AST).
|
|
|
|
The fundamental idea of Loom is that presentation and content are orthogonal
|
|
dimensions of data. A communication has values in these two dimensions
|
|
integrated into a coherent whole.
|
|
|
|
## When should I use this?
|
|
|
|
When you want to blend form (such as HTML) with content (such as JSON) into
|
|
a single document. Unlike other systems, Loom does not require writing to
|
|
or reading from files.
|
|
|
|
## Installation
|
|
|
|
`$` `npm install @thefarce/loom`
|
|
|
|
## Usage Example
|
|
|
|
For more thorough usage examples, see the `examples` directory and refer to
|
|
the [transformers documentation](./docs/usage.md) and the [interpolation
|
|
documentation](./docs/interpolation.md).
|
|
|
|
### Simple Example
|
|
|
|
In this simple example, we will make two changes. First, we will replace
|
|
the `div` tag in our html fragment with a `span` tag. Second, we will
|
|
replace the `name` variable in our template with the value `Othello`.
|
|
|
|
```js
|
|
import { interpolateTree, transform } from '@thefarce/loom'
|
|
import { astToHtml, htmlToAst } from '@thefarce/loom-html5'
|
|
|
|
// Get our HTML fragment.
|
|
const ast = htmlToAst('<p>Hello, <div>{name}</div>!</p>', { fragment: true });
|
|
|
|
// Now we have an abstract syntax tree (AST) representation of our HTML
|
|
// fragment. First, let's transform the div to a span.
|
|
|
|
let updated = transform(
|
|
// our initial syntax tree
|
|
ast,
|
|
// A transformer that checks if the node is an element and has a tag name
|
|
// of "div". If so, we just change the tag name to "span". It is
|
|
// important that we return the updated node (or a new one).
|
|
(node) => {
|
|
if (node.type === 'element' && node.tagName === 'div') {
|
|
node.tagName = 'span';
|
|
return node;
|
|
}
|
|
}
|
|
);
|
|
|
|
// Now let's interpolate the value `name`. There is another major mechanism
|
|
// for providing interpolation values; see the for more detailed information.
|
|
let interpolated = interpolateTree(
|
|
updated,
|
|
{ name: 'Othello' }
|
|
);
|
|
|
|
console.log(astToHtml(interpolated));
|
|
```
|
|
|
|
Running this script produces the following output:
|
|
|
|
```html
|
|
<p>Hello, Othello!</p>
|
|
```
|
|
|
|
## API
|
|
|
|
### Value Interpolation
|
|
|
|
Interpolation is the process of executing code within the AST's values.
|
|
This uses a syntax identical to JavaScript's "backtick" interpolation. For
|
|
example, in the following script, JavaScript will replace `{name}` with the
|
|
value `Othello`:
|
|
|
|
See the [interpolation documentation](./docs/interpolation.md) for more
|
|
detailed information.
|
|
|
|
```js
|
|
const name = 'Othello';
|
|
console.log(`Hello, ${name}!`);
|
|
```
|
|
|
|
This interpolation uses variables in scope to expand values. Loom
|
|
interpolation works the same way: any string[^1] in the AST will be replaced
|
|
with the value in the data.
|
|
|
|
[^1]: There are a few exceptions. The `type`, `data`, and `position` values of a node will not be interpolated. You may interpolate them manually, of course.
|
|
|
|
### AST Transformation
|
|
|
|
Transformation is the process of making systematic changes to an AST. This
|
|
is accomplished by creating "transformer functions" (or "transformers") that
|
|
apply changes to a node based on its content.
|
|
|
|
See the [transformations documentation](./docs/transformations.md) for more
|
|
detailed information.
|
|
|
|
## Glossary
|
|
|
|
### ast
|
|
|
|
The AST to be transformed. This can be any AST that conforms to the
|
|
Unified.js specification.
|
|
|
|
## Contributing to Loom
|
|
|
|
Contributions to Loom are welcome.
|
|
|
|
### Community Guidelines
|
|
|
|
Contribute good code with full tests and docs, then submit a pull request.
|
|
I don't care about any of your other behaviors.
|
|
|
|
### VIM
|
|
|
|
This project contains a `.vimrc` file to help with development and
|
|
maintainance. See that file for more information and instructions for use.
|
|
|