Labyricorn/liquidjs
1
0
Fork 0
mirror of https://github.com/harttle/liquidjs.git synced 2026-09-16 21:00:40 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc: migrate README to wiki

harttle
2019-08-06 00:51:59 +08:00
parent b4ddec07e6
commit 634afe7b60
11 changed files with 198 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Basic-Usage.md
+23
@@ -0,0 +1,23 @@
Render a template string with a context:
```javascript
var Liquid = require('liquidjs');
var engine = new Liquid();
engine
.parseAndRender('{{name | capitalize}}', {name: 'alice'})
.then(console.log); // outputs 'Alice'
```
Parsed template can be cached:
```javascript
// cache the parsed tpl
var tpl = engine.parse('{{name | capitalize}}');
engine
// render the cached tpl with a scope
.render(tpl, {name: 'alice'})
.then(console.log); // outputs 'Alice'
```
Get-Started.md
Operators.md
+1 -4
@@ -1,6 +1,3 @@
Documentation: <https://shopify.github.io/liquid/basics/operators/>
Operators supported:
Please refer to the operators document from Shopify: <https://shopify.github.io/liquid/basics/operators/>. Operators supported by LiquidJS are:
`==`, `!=`, `>`, `<`, `>=`, `<=`, `or`, `and`, `contains`.
Partials-and-Layouts.md
+44
@@ -0,0 +1,44 @@
## 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
```
* A layout file can define multiple blocks.
* Block name is optional when there's only one block.
Register-Filters-Tags.md
+35
@@ -0,0 +1,35 @@
## 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>
Render-a-File.md
+11
@@ -0,0 +1,11 @@
To render a file, you need to specify a root directory and call the `renderFile` method:
```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"
```
Truthy-and-Falsy.md
+13 -13
@@ -4,19 +4,19 @@ Everything other than `false` and `nil` is truthy in the ruby version, see: <htt
In this JavaScript version, things are slightly different:
value | truthy | falsy
--- | --- | ---
`true` | ✔️ |
`false` | | ✔️
`null` | | ✔️
`undefined` | | ✔️
`string` | ✔️ |
`empty string` | ✔️ |
`0` | ✔️ |
`integer` | ✔️ |
`float` | ✔️ |
`array` | ✔️ |
`empty array` | ✔️ |
value | truthy | falsy
--- | --- | ---
`true` | ✔️ |
`false` | | ✔️
`null` | | ✔️
`undefined` | | ✔️
`string` | ✔️ |
`empty string` | ✔️ |
`0` | ✔️ |
`integer` | ✔️ |
`float` | ✔️ |
`array` | ✔️ |
`empty array` | ✔️ |
[ruby]: https://shopify.github.io/liquid
[sl]: https://www.npmjs.com/package/liquidjs
Use-with-Expressjs.md
+11
@@ -0,0 +1,11 @@
LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html):
```javascript
// register liquid engine
app.engine('liquid', engine.express());
app.set('views', './views'); // specify the views directory
app.set('view engine', 'liquid'); // set liquid to default
```
[`views`][express-views] variable in express.js will also be respected
for partial (includes and layouts) look up.
Whitespace-Control.md
+4 -4
@@ -38,10 +38,10 @@ harttle
To enable whitespace control without spreading changes, use these options:
* `trim_tag_left`
* `trim_tag_right`
* `trim_value_right`
* `trim_value_right`
* `trimTagLeft`
* `trimTagRight`
* `trimValueRight`
* `trimValueRight`
[liquidjs][liquidjs] will **NOT** trim any whitespace by default, i.e. above options all default to `false`.
For details of these options, see the [README](https://github.com/harttle/liquidjs).
Write-a-Plugin.md
+35
@@ -0,0 +1,35 @@
A number of tags and filters can be encapsulated into a **plugin**, which will be typically installed via npm.
This article provides information about how to create and use a plugin
## A Simple Plugin
We'll make a plugin to upper case every letter of the input,
save the following snippet to `upup.js`:
```javascript
/**
* Inside the plugin function, `this` refers to the Liquid instance.
*
* @param Liquid: provides facilities to implement tags and filters.
*/
module.exports = function (Liquid) {
this.registerFilter('upup', x => x.toUpperCase());
}
```
## Introduce a Plugin
Simply pass the plugin function into the `.plugin()` method:
```javascript
const engine = new Liquid()
engine.plugin(require('./upup.js'));
engine
.parseAndRender('{{ "foo" | upup }}')
.then(console.log) // outputs "FOO"
```
## Plugin List
See <https://github.com/harttle/liquidjs>.
_Sidebar.md
+21 -6
@@ -1,6 +1,21 @@
* **[Home](/harttle/liquidjs/wiki)**
* **[Builtin Filters](/harttle/liquidjs/wiki/Builtin-Filters)**
* **[Builtin Tags](/harttle/liquidjs/wiki/Builtin-Tags)**
* **[Operators](/harttle/liquidjs/wiki/Operators)**
* **[Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy)**
* **[Whitespace Control](/harttle/liquidjs/wiki/Whitespace-Control)**
* [Home](/harttle/liquidjs/wiki)
* Tutorial
* [Basic Usage](/harttle/liquidjs/wiki/Basic-Usage)
* [Render a File](/harttle/liquidjs/wiki/Render-a-File)
* [Use with Express.js](/harttle/liquidjs/wiki/Use-with-Expressjs)
* [Partials and Layouts](/harttle/liquidjs/wiki/Partials-and-Layouts)
* [Whitespace Control](/harttle/liquidjs/wiki/Whitespace-Control)
* [Register Filters/Tags](/harttle/liquidjs/wiki/Register-Filters-Tags)
* [Write a Plugin](/harttle/liquidjs/wiki/Write-a-Plugin)
* API
* [Options](/harttle/liquidjs/blob/master/doc/interfaces/_liquid_options_.liquidoptions.html)
* [Builtin Filters](/harttle/liquidjs/wiki/Builtin-Filters)
* [Builtin Tags](/harttle/liquidjs/wiki/Builtin-Tags)
* [Operators](/harttle/liquidjs/wiki/Operators)
* [Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy)
* Demos
* Node.js: [/demo/node/](demo/node/)
* 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/)