mirror of
https://github.com/harttle/liquidjs.git
synced 2026-09-20 15:00:42 -07:00
doc: introduce typedoc and sponsorship, for #126
This commit is contained in:
harttle
@@ -1,23 +1,43 @@
|
||||
# liquidjs
|
||||
|
||||
[](https://www.npmjs.org/package/liquidjs)
|
||||
[](https://www.npmjs.org/package/liquidjs)
|
||||
[](https://www.npmjs.org/package/liquidjs)
|
||||
[](https://www.npmjs.org/package/liquidjs)
|
||||
[](https://travis-ci.org/harttle/liquidjs)
|
||||
[](https://coveralls.io/github/harttle/liquidjs?branch=master)
|
||||
[](https://david-dm.org/harttle/liquidjs)
|
||||
[](#contributors-)
|
||||
[](https://github.com/harttle/liquidjs)
|
||||
[](https://github.com/harttle/liquidjs/issues)
|
||||
[](https://github.com/harttle/liquidjs/graphs/contributors)
|
||||
[](https://david-dm.org/harttle/liquidjs)
|
||||
[](https://david-dm.org/harttle/liquidjs?type=dev)
|
||||
[](https://github.com/harttle/liquidjs/blob/master/LICENSE)
|
||||
[](http://github.com/harttle/liquidjs)
|
||||
[](https://github.com/harttle/liquidjs)
|
||||
[](https://github.com/harttle/liquidjs/blob/master/LICENSE)
|
||||
[](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)
|
||||
[](https://opencollective.com/liquidjs)
|
||||
|
||||
A [shopify][shopify/liquid] compatible [Liquid][tutorial] template engine in pure JavaScript. Install via npm:
|
||||
A [shopify][shopify/liquid] compatible [Liquid][tutorial] template engine in pure JavaScript.
|
||||
**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community.
|
||||
All features, filters and tags in [shopify/liquid](https://github.com/Shopify/liquid) are supposed to be built in LiquidJS,
|
||||
though there are still some differences and limitations (see below).
|
||||
|
||||
[Donate to our collective](https://opencollective.com/liquidjs/donate) if you like liquidjs.
|
||||
|
||||
## Get Started
|
||||
|
||||
Install via npm:
|
||||
|
||||
```bash
|
||||
npm install --save liquidjs
|
||||
```
|
||||
|
||||
```javascript
|
||||
var Liquid = require('liquidjs');
|
||||
var engine = new Liquid();
|
||||
|
||||
engine
|
||||
.parseAndRender('{{name | capitalize}}', {name: 'alice'})
|
||||
.then(console.log); // outputs 'Alice'
|
||||
```
|
||||
|
||||
Or include the UMD build (You may need a [Promise polyfill][pp] for Node.js < 4 and ES5 browsers like [IE and Android UC][caniuse-promises]):
|
||||
|
||||
```html
|
||||
@@ -25,9 +45,15 @@ Or include the UMD build (You may need a [Promise polyfill][pp] for Node.js <
|
||||
<script src="//unpkg.com/liquidjs/dist/liquid.js"></script> <!--for development-->
|
||||
```
|
||||
|
||||
**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community.
|
||||
All features, filters and tags in [shopify/liquid](https://github.com/Shopify/liquid) are supposed to be supported here,
|
||||
though there are still some differences:
|
||||
Also available from CLI:
|
||||
|
||||
```bash
|
||||
echo '{{"hello" | capitalize}}' | npx liquidjs
|
||||
```
|
||||
|
||||
For more tutorials and the full API, refer to the [wiki page](https://github.com/harttle/liquidjs/wiki).
|
||||
|
||||
## Differences and Limitations
|
||||
|
||||
* Dynamic file locating (enabled by default), that means layout/partial names are treated as variables in liquidjs. See [#51](https://github.com/harttle/liquidjs/issues/51).
|
||||
* Truthy and Falsy. All values except `undefined`, `null`, `false` are truthy, whereas in Ruby Liquid all except `nil` and `false` are truthy. See [#26](https://github.com/harttle/liquidjs/pull/26).
|
||||
@@ -41,231 +67,51 @@ but there're some plugins available (feel free to add yours):
|
||||
* color filters: https://github.com/harttle/liquidjs-color-filters
|
||||
* sections tags (WIP): https://github.com/harttle/liquidjs-section-tags
|
||||
|
||||
## TOC
|
||||
## Contributors ✨
|
||||
|
||||
* Get Started
|
||||
* [Render from String](#render-from-string)
|
||||
* [Render from File](#render-from-file)
|
||||
* [Use with Express.js](#use-with-expressjs)
|
||||
* [Include Partials](#include-partials)
|
||||
* [Layout Templates (Extends)](#layout-templates-extends)
|
||||
* Demos
|
||||
* Node.js: [/demo/nodejs/](demo/nodejs/)
|
||||
* Browser: <https://jsfiddle.net/6u40xbzs/>, [/demo/browser/](demo/browser/).
|
||||
* Express.js: [/demo/express/](demo/express/)
|
||||
* TypeScript: [/demo/typescript/](demo/typescript/)
|
||||
* React JS: [/demo/reactjs/](demo/reactjs/)
|
||||
* Advanced
|
||||
* [Options](#options)
|
||||
* [Register Filters](#register-filters), [Builtin Filters](https://github.com/harttle/liquidjs/wiki/Builtin-Filters)
|
||||
* [Register Tags](#register-tags), [Builtin Tags](https://github.com/harttle/liquidjs/wiki/Builtin-Tags)
|
||||
* [Operators](https://github.com/harttle/liquidjs/wiki/Operators)
|
||||
* [Whitespace Control](https://github.com/harttle/liquidjs/wiki/Whitespace-Control)
|
||||
* [Plugin API](#plugin-api)
|
||||
* [Contribute Guidelines](#contribute-guidelines)
|
||||
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
|
||||
Contributions of any [kind](https://allcontributors.org/docs/en/emoji-key) are welcome!
|
||||
Thanks goes to these wonderful people:
|
||||
|
||||
## Render from String
|
||||
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
|
||||
<!-- prettier-ignore-start -->
|
||||
<!-- markdownlint-disable -->
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center"><a href="https://harttle.land"><img src="https://avatars3.githubusercontent.com/u/4427974?v=4" width="100px;" alt="Jun Yang"/><br /><sub><b>Jun Yang</b></sub></a><br /><a href="#maintenance-harttle" title="Maintenance">🚧</a> <a href="https://github.com/harttle/liquidjs/commits?author=harttle" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://github.com/chenos"><img src="https://avatars0.githubusercontent.com/u/2993310?v=4" width="100px;" alt="chenos"/><br /><sub><b>chenos</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=chenos" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://zachleat.com/"><img src="https://avatars2.githubusercontent.com/u/39355?v=4" width="100px;" alt="Zach Leatherman"/><br /><sub><b>Zach Leatherman</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/issues?q=author%3Azachleat" title="Bug reports">🐛</a></td>
|
||||
<td align="center"><a href="https://github.com/thardy"><img src="https://avatars3.githubusercontent.com/u/120636?v=4" width="100px;" alt="Tim Hardy"/><br /><sub><b>Tim Hardy</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=thardy" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://paulrobertlloyd.com/"><img src="https://avatars3.githubusercontent.com/u/813383?v=4" width="100px;" alt="Paul Robert Lloyd"/><br /><sub><b>Paul Robert Lloyd</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=paulrobertlloyd" title="Code">💻</a> <a href="https://github.com/harttle/liquidjs/issues?q=author%3Apaulrobertlloyd" title="Bug reports">🐛</a></td>
|
||||
<td align="center"><a href="https://twitter.com/alecdotbiz"><img src="https://avatars2.githubusercontent.com/u/1925840?v=4" width="100px;" alt="Alec Larson"/><br /><sub><b>Alec Larson</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=aleclarson" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://github.com/pmalouin"><img src="https://avatars1.githubusercontent.com/u/1411117?v=4" width="100px;" alt="Patrick Malouin"/><br /><sub><b>Patrick Malouin</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=pmalouin" title="Code">💻</a> <a href="https://github.com/harttle/liquidjs/commits?author=pmalouin" title="Documentation">📖</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><a href="https://jaswrks.com"><img src="https://avatars3.githubusercontent.com/u/1563559?v=4" width="100px;" alt="jaswrks"/><br /><sub><b>jaswrks</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=jaswrks" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://oott123.com"><img src="https://avatars2.githubusercontent.com/u/905663?v=4" width="100px;" alt="三三"/><br /><sub><b>三三</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=oott123" title="Code">💻</a> <a href="#ideas-oott123" title="Ideas, Planning, & Feedback">🤔</a></td>
|
||||
<td align="center"><a href="https://github.com/ssendev"><img src="https://avatars0.githubusercontent.com/u/450793?v=4" width="100px;" alt="ssendev"/><br /><sub><b>ssendev</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=ssendev" title="Code">💻</a> <a href="https://github.com/harttle/liquidjs/commits?author=ssendev" title="Documentation">📖</a></td>
|
||||
<td align="center"><a href="https://github.com/wojtask9"><img src="https://avatars3.githubusercontent.com/u/6099236?v=4" width="100px;" alt="wojtask9"/><br /><sub><b>wojtask9</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=wojtask9" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://github.com/thelornenelson"><img src="https://avatars3.githubusercontent.com/u/24596583?v=4" width="100px;" alt="Andrew Barclay"/><br /><sub><b>Andrew Barclay</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=thelornenelson" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://www.stam.pr/"><img src="https://avatars2.githubusercontent.com/u/142338?v=4" width="100px;" alt="Cory Mawhorter"/><br /><sub><b>Cory Mawhorter</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=cmawhorter" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://github.com/thehappybug"><img src="https://avatars0.githubusercontent.com/u/3393530?v=4" width="100px;" alt="Mehdi Jaffery"/><br /><sub><b>Mehdi Jaffery</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=thehappybug" title="Code">💻</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><a href="https://github.com/robinbijlani"><img src="https://avatars0.githubusercontent.com/u/2503108?v=4" width="100px;" alt="Robin Bijlani"/><br /><sub><b>Robin Bijlani</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=robinbijlani" title="Code">💻</a> <a href="https://github.com/harttle/liquidjs/issues?q=author%3Arobinbijlani" title="Bug reports">🐛</a></td>
|
||||
<td align="center"><a href="https://www.rmkennedy.com"><img src="https://avatars3.githubusercontent.com/u/8356669?v=4" width="100px;" alt="Ryan Kennedy"/><br /><sub><b>Ryan Kennedy</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=ryaninvents" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://github.com/strax"><img src="https://avatars2.githubusercontent.com/u/587213?v=4" width="100px;" alt="Sami Kukkonen"/><br /><sub><b>Sami Kukkonen</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=strax" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://ScottFreeCode.github.io/"><img src="https://avatars3.githubusercontent.com/u/16506071?v=4" width="100px;" alt="Scott Santucci"/><br /><sub><b>Scott Santucci</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=ScottFreeCode" title="Code">💻</a></td>
|
||||
<td align="center"><a href="http://stevenrescigno.com"><img src="https://avatars3.githubusercontent.com/u/8505293?v=4" width="100px;" alt="Steven "/><br /><sub><b>Steven </b></sub></a><br /><a href="#example-stevenanthonyrevo" title="Examples">💡</a> <a href="https://github.com/harttle/liquidjs/commits?author=stevenanthonyrevo" title="Code">💻</a></td>
|
||||
<td align="center"><a href="https://efcl.info/"><img src="https://avatars1.githubusercontent.com/u/19714?v=4" width="100px;" alt="azu"/><br /><sub><b>azu</b></sub></a><br /><a href="https://github.com/harttle/liquidjs/commits?author=azu" title="Documentation">📖</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Just render a template string with a context:
|
||||
<!-- markdownlint-enable -->
|
||||
<!-- prettier-ignore-end -->
|
||||
<!-- ALL-CONTRIBUTORS-LIST:END -->
|
||||
|
||||
```javascript
|
||||
var Liquid = require('liquidjs');
|
||||
var engine = new Liquid();
|
||||
[](https://opencollective.com/liquidjs/donate)
|
||||
|
||||
engine
|
||||
.parseAndRender('{{name | capitalize}}', {name: 'alice'})
|
||||
.then(console.log); // outputs 'Alice'
|
||||
```
|
||||
|
||||
Caching parsed templates:
|
||||
|
||||
```javascript
|
||||
var tpl = engine.parse('{{name | capitalize}}');
|
||||
engine
|
||||
.render(tpl, {name: 'alice'})
|
||||
.then(console.log); // outputs 'Alice'
|
||||
```
|
||||
|
||||
## Render from File
|
||||
|
||||
```javascript
|
||||
var engine = new Liquid({
|
||||
root: path.resolve(__dirname, 'views/'), // root for layouts/includes lookup
|
||||
extname: '.liquid' // used for layouts/includes, defaults ""
|
||||
});
|
||||
engine
|
||||
.renderFile("hello", {name: 'alice'}) // will read and render `views/hello.liquid`
|
||||
.then(console.log) // outputs "Alice"
|
||||
```
|
||||
|
||||
Or from the CLI:
|
||||
|
||||
```bash
|
||||
echo '{{ "hello" | capitalize }}' | liquidjs
|
||||
```
|
||||
|
||||
## Use with Express.js
|
||||
|
||||
```javascript
|
||||
// register liquid engine
|
||||
app.engine('liquid', engine.express());
|
||||
app.set('views', './views'); // specify the views directory
|
||||
app.set('view engine', 'liquid'); // set to default
|
||||
```
|
||||
|
||||
[`views`][express-views] in express.js will be included when looking up
|
||||
partials(includes and layouts).
|
||||
|
||||
## Include Partials
|
||||
|
||||
```
|
||||
// file: color.liquid
|
||||
color: '{{ color }}' shape: '{{ shape }}'
|
||||
|
||||
// file: theme.liquid
|
||||
{% assign shape = 'circle' %}
|
||||
{% include 'color' %}
|
||||
{% include 'color' with 'red' %}
|
||||
{% include 'color', color: 'yellow', shape: 'square' %}
|
||||
```
|
||||
|
||||
The output will be:
|
||||
|
||||
```
|
||||
color: '' shape: 'circle'
|
||||
color: 'red' shape: 'circle'
|
||||
color: 'yellow' shape: 'square'
|
||||
```
|
||||
|
||||
## Layout Templates (Extends)
|
||||
|
||||
```
|
||||
// file: default-layout.liquid
|
||||
Header
|
||||
{% block content %}My default content{% endblock %}
|
||||
Footer
|
||||
|
||||
// file: page.liquid
|
||||
{% layout "default-layout" %}
|
||||
{% block content %}My page content{% endblock %}
|
||||
```
|
||||
|
||||
The output of `page.liquid`:
|
||||
|
||||
```
|
||||
Header
|
||||
My page content
|
||||
Footer
|
||||
```
|
||||
|
||||
* It's possible to define multiple blocks.
|
||||
* block name is optional when there's only one block.
|
||||
|
||||
## Options
|
||||
|
||||
The full list of options for `Liquid()` is listed as following:
|
||||
|
||||
* `root` is a directory or an array of directories to resolve layouts and includes, as well as the filename passed in when calling `.renderFile()`.
|
||||
If an array, the files are looked up in the order they occur in the array.
|
||||
Defaults to `["."]`
|
||||
|
||||
* `extname` is used to lookup the template file when filepath doesn't include an extension name. Eg: setting to `".html"` will allow including file by basename. Defaults to `""`.
|
||||
|
||||
* `cache` indicates whether or not to cache resolved templates. Defaults to `false`.
|
||||
|
||||
* `dynamicPartials`: if set, treat `<filepath>` parameter in `{%include filepath %}`, `{%layout filepath%}` as a variable, otherwise as a literal value. Defaults to `true`.
|
||||
|
||||
* `strictFilters` is used to enable strict filter existence. If set to `false`, undefined filters will be rendered as empty string. Otherwise, undefined filters will cause an exception. Defaults to `false`.
|
||||
|
||||
* `strictVariables` is used to enable strict variable derivation.
|
||||
If set to `false`, undefined variables will be rendered as empty string.
|
||||
Otherwise, undefined variables will cause an exception. Defaults to `false`.
|
||||
|
||||
* `trimTagRight` is used to strip blank characters (including ` `, `\t`, and `\r`) from the right of tags (`{% %}`) until `\n` (inclusive). Defaults to `false`.
|
||||
|
||||
* `trimTagLeft` is similiar to `trimTagRight`, whereas the `\n` is exclusive. Defaults to `false`. See [Whitespace Control][whitespace control] for details.
|
||||
|
||||
* `trimOutputRight` is used to strip blank characters (including ` `, `\t`, and `\r`) from the right of values (`{{ }}`) until `\n` (inclusive). Defaults to `false`.
|
||||
|
||||
* `trimOutputLeft` is similiar to `trimOutputRight`, whereas the `\n` is exclusive. Defaults to `false`. See [Whitespace Control][whitespace control] for details.
|
||||
|
||||
* `tagDelimiterLeft` and `tagDelimiterRight` are used to override the delimiter for liquid tags.
|
||||
|
||||
* `outputDelimiterLeft` and `outputDelimiterRight` are used to override the delimiter for liquid outputs.
|
||||
|
||||
* `greedy` is used to specify whether `trim*Left`/`trim*Right` is greedy. When set to `true`, all consecutive blank characters including `\n` will be trimed regardless of line breaks. Defaults to `true`.
|
||||
|
||||
* `fs` is used to override the default file-system module with a custom implementation.
|
||||
|
||||
## Register Filters
|
||||
|
||||
```javascript
|
||||
// Usage: {{ name | uppper }}
|
||||
engine.registerFilter('upper', v => v.toUpperCase())
|
||||
```
|
||||
|
||||
Filter arguments will be passed to the registered filter function, for example:
|
||||
|
||||
```javascript
|
||||
// Usage: {{ 1 | add: 2, 3 }}
|
||||
engine.registerFilter('add', (initial, arg1, arg2) => initial + arg1 + arg2)
|
||||
```
|
||||
|
||||
See existing filter implementations here: <https://github.com/harttle/liquidjs/tree/master/src/builtin/filters>
|
||||
|
||||
## Register Tags
|
||||
|
||||
```javascript
|
||||
// Usage: {% upper name%}
|
||||
engine.registerTag('upper', {
|
||||
parse: function(tagToken, remainTokens) {
|
||||
this.str = tagToken.args; // name
|
||||
},
|
||||
render: async function(scope, hash) {
|
||||
var str = await Liquid.evalValue(this.str, scope); // 'alice'
|
||||
return str.toUpperCase() // 'Alice'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
* `parse`: Read tokens from `remainTokens` until your end token.
|
||||
* `render`: Combine scope data with your parsed tokens into HTML string.
|
||||
|
||||
See existing tag implementations here: <https://github.com/harttle/liquidjs/tree/master/src/builtin/tags>
|
||||
|
||||
## Plugin API
|
||||
|
||||
A pack of tags or filters can be encapsulated into a **plugin**, which will be typically installed via npm.
|
||||
|
||||
```javascript
|
||||
engine.plugin(require('./some-plugin'));
|
||||
|
||||
// some-plugin.js
|
||||
module.exports = function (Liquid) {
|
||||
// here `this` refers to the engine instance
|
||||
// `Liquid` provides facilities to implement tags and filters
|
||||
this.registerFilter('foo', x => x);
|
||||
}
|
||||
```
|
||||
|
||||
## Contribute Guidelines
|
||||
|
||||
This repo uses [eslint](https://eslint.org/) to check code style, [semantic-release](https://github.com/semantic-release/semantic-release) to generate changelog and publish to npm and Github Releases.
|
||||
|
||||
* Code Style: <https://github.com/standard/eslint-config-standard>, `npm run lint` to check locally.
|
||||
* Commit Message: <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits>
|
||||
|
||||
[nunjucks]: http://mozilla.github.io/nunjucks/
|
||||
[liquid-node]: https://github.com/sirlantis/liquid-node
|
||||
[shopify/liquid]: https://shopify.github.io/liquid/
|
||||
[jekyll]: http://jekyllrb.com/
|
||||
[gh]: https://pages.github.com/
|
||||
[any-promise]: https://github.com/kevinbeaty/any-promise
|
||||
[test]: https://github.com/harttle/liquidjs/tree/master/test
|
||||
[caniuse-promises]: http://caniuse.com/#feat=promises
|
||||
[whitespace control]: https://github.com/harttle/liquidjs/wiki/Whitespace-Control
|
||||
[tags]: https://github.com/harttle/liquidjs/wiki/Builtin-Tags
|
||||
[filters]: https://github.com/harttle/liquidjs/wiki/Builtin-Filters
|
||||
[express-views]: http://expressjs.com/en/guide/using-template-engines.html
|
||||
[pp]: https://github.com/taylorhakes/promise-polyfill
|
||||
[tutorial]: https://shopify.github.io/liquid/basics/introduction/
|
||||
[tutorial]: https://shopify.github.io/liquid/basics/introduction/
|
||||
Reference in New Issue
Block a user