3.7 KiB
@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 and the interpolation
documentation.
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
.
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:
<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 for more detailed information.
const name = 'Othello';
console.log(`Hello, ${name}!`);
This interpolation uses variables in scope to expand values. Loom interpolation works the same way: any string1 in the AST will be replaced with the value in the data.
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 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.
-
There are a few exceptions. The
type
,data
, andposition
values of a node will not be interpolated. You may interpolate them manually, of course. ↩︎