mirror of
https://github.com/harttle/liquidjs.git
synced 2026-09-16 04:40:39 -07:00
docs: re-organize wiki pages, see #159
harttle
-23
@@ -1,23 +0,0 @@
|
||||
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'
|
||||
```
|
||||
|
||||
+1
-1
@@ -21,5 +21,5 @@ Tag | Document | Source | Test
|
||||
`raw` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#raw) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/raw.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/raw.ts)
|
||||
`comment` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#comment) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/comment.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/comment.ts)
|
||||
`include` | [Document](https://help.shopify.com/themes/liquid/tags/theme-tags#include) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/include.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/include.ts)
|
||||
`layout, block` | [Document](http://docs.mixture.io/templates/) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/layout.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/layout.ts)
|
||||
`layout, block` | [Document](https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout) | [Source](/harttle/liquidjs/blob/master/src/builtin/tags/layout.ts) | [Test](/harttle/liquidjs/blob/master/test/unit/tags/layout.ts)
|
||||
|
||||
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
In a typical website project, we'll have a directory of view templates and they'll be rendered multiple times. In production environment the template files are not likely to be changed overtime (other than re-deployments). Thus it's a waste of time to repeatedly read from file system and parse the template string each time. LiquidJS provides multiple ways to cache the parsed templates to improve performance.
|
||||
|
||||
## Programmaticly
|
||||
|
||||
The [parse][parse], [parseFile][parseFile], [parseFileSync][parseFileSync] APIs are used to parse templates from string or files. The result template can be then rendered multiple times with different context.
|
||||
|
||||
Parse from string:
|
||||
|
||||
```javascript
|
||||
var tpl = engine.parse('{{name | capitalize}}');
|
||||
|
||||
engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
|
||||
engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
|
||||
```
|
||||
|
||||
Parse from file:
|
||||
|
||||
```javascript
|
||||
var tpl = engine.parseFileSync('hello'); // contents of `hello.liquid`: {{name}}
|
||||
|
||||
engine.renderSync(tpl, {name: 'alice'}) // 'Alice'
|
||||
engine.renderSync(tpl, {name: 'bob'}) // 'Bob'
|
||||
```
|
||||
|
||||
## The `cache` Option
|
||||
|
||||
The [cache option][cache] can be set to instruct liquidjs to use cached parsed templates each time you call [renderFile][renderFile] or [renderFileSync][renderFileSync].
|
||||
|
||||
```javascript
|
||||
var { Liquid } = require('liquidjs');
|
||||
var engine = new Liquid({
|
||||
cache: true
|
||||
});
|
||||
|
||||
// liquidjs parses the hello.liquid, then renders it with {name: 'alice'}
|
||||
engine.renderFileSync('hello', {name: 'alice'})
|
||||
|
||||
// liquidjs finds the cached template, then renders it with {name: 'bob'}
|
||||
engine.renderFileSync('hello', {name: 'bob'})
|
||||
```
|
||||
|
||||
[parse]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parse
|
||||
[parseFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefile
|
||||
[parseFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefilesync
|
||||
[renderFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfile
|
||||
[renderFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfilesync
|
||||
+66
-1
@@ -1 +1,66 @@
|
||||
Welcome to the liquidjs wiki!
|
||||
Welcome to the liquidjs wiki! Liquidjs is a shopify compatible Liquid template engine in pure JavaScript. The purpose of this repo is to provide a standard Liquid implementation for the JavaScript community.
|
||||
|
||||
## 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, a live demo is available on jsfiddle: <https://jsfiddle.net/x43eb0z6/>. You may need a [Promise polyfill][pp] for Node.js < 4 and ES5 browsers like [IE and Android UC][caniuse-promises].
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/liquidjs/dist/liquid.min.js"></script> <!--for production-->
|
||||
<script src="//unpkg.com/liquidjs/dist/liquid.js"></script> <!--for development-->
|
||||
```
|
||||
|
||||
Also available from CLI:
|
||||
|
||||
```bash
|
||||
echo '{{"hello" | capitalize}}' | npx liquidjs
|
||||
```
|
||||
|
||||
## More Demos
|
||||
|
||||
There's [a live demo][jsfiddle] on JSFiddle, and a list of demo projects in [the demo/ directory][demo-dir]
|
||||
|
||||
* [JSFiddle][jsfiddle]
|
||||
* [Demo for Node.js](/harttle/liquidjs/blob/master/demo/node/)
|
||||
* [Demo in TypeScript](/harttle/liquidjs/blob/master/demo/typescript/)
|
||||
* [Demo for Browser Usage](/harttle/liquidjs/blob/master/demo/browser/)
|
||||
* [Demo for Express.js Usage](/harttle/liquidjs/blob/master/demo/express/)
|
||||
* [Demo for ReactJS Usage](/harttle/liquidjs/blob/master/demo/reactjs/)
|
||||
|
||||
## Documentation
|
||||
|
||||
The tutorials contains a list of articles for advanced use cases, performance optimization and extending liquidjs.
|
||||
|
||||
* [Render a Template File](/harttle/liquidjs/wiki/Render-a-File)
|
||||
* [Caching](/harttle/liquidjs/wiki/Caching)
|
||||
* [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)
|
||||
* [Plugins](/harttle/liquidjs/wiki/Plugins)
|
||||
* [Migrate to 9.0.0](/harttle/liquidjs/wiki/Migrate-to-9)
|
||||
|
||||
The [API Reference](https://harttle.github.io/liquidjs/classes/_liquid_.liquid.html) provides detailed descriptions for classes, methods and properties.
|
||||
|
||||
* [Options](https://harttle.github.io/liquidjs/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)
|
||||
|
||||
[jsfiddle]: https://jsfiddle.net/x43eb0z6/
|
||||
[demo-dir]: https://github.com/harttle/liquidjs/tree/master/demo
|
||||
@@ -1,7 +1,7 @@
|
||||
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
|
||||
## Write a Plugin
|
||||
|
||||
We'll make a plugin to upper case every letter of the input,
|
||||
save the following snippet to `upup.js`:
|
||||
@@ -17,7 +17,7 @@ module.exports = function (Liquid) {
|
||||
}
|
||||
```
|
||||
|
||||
## Introduce a Plugin
|
||||
## Use a Plugin
|
||||
|
||||
Simply pass the plugin function into the `.plugin()` method:
|
||||
|
||||
@@ -37,4 +37,6 @@ See <https://github.com/harttle/liquidjs#differences-and-limitations>.
|
||||
Since this library excludes certain features that are available on the Shopify platform but not on the [Shopify/liquid](https://github.com/Shopify/liquid/) repo, see the following plugins that backfill those features:
|
||||
|
||||
* Sections Tags (WIP): https://github.com/harttle/liquidjs-section-tags
|
||||
* Color Filters: https://github.com/harttle/liquidjs-color-filters
|
||||
* Color Filters: https://github.com/harttle/liquidjs-color-filters
|
||||
|
||||
> Feel free to add yours, this file is publicly editable.
|
||||
+43
-1
@@ -1,4 +1,19 @@
|
||||
To render a file, you need to specify a root directory and call the `renderFile` method:
|
||||
For a typical project there could be a directory of template files, you'll need to set the [template root][root] and call [renderFile][renderFile] or [renderFileSync][renderFileSync] to render a specific file.
|
||||
|
||||
## Render a File
|
||||
|
||||
For example you have a directory of templates like this:
|
||||
|
||||
```
|
||||
.
|
||||
├── index.js
|
||||
└── views/
|
||||
├── hello.liquid
|
||||
└── world.liquid
|
||||
```
|
||||
|
||||
`hello.liquid` contains a single line `name: {{name}}`.
|
||||
Now save the following contents into `index.js`:
|
||||
|
||||
```javascript
|
||||
var engine = new Liquid({
|
||||
@@ -9,3 +24,30 @@ engine
|
||||
.renderFile("hello", {name: 'alice'}) // will read and render `views/hello.liquid`
|
||||
.then(console.log) // outputs "Alice"
|
||||
```
|
||||
|
||||
Run `node index.js` and you'll get output like this:
|
||||
|
||||
```
|
||||
> node index.js
|
||||
name: alice
|
||||
```
|
||||
|
||||
## Template Lookup
|
||||
|
||||
Template files names passed to [renderFile][renderFile], [parseFile][parseFile], [renderFileSync][renderFileSync], [parseFileSync][parseFileSync] APIs,
|
||||
and [include][include], [layout][layout] tags are resolved against [the root option][root].
|
||||
|
||||
It can be a string-typed path (see above example), or a list of root directories, in which case templates will be looked up in that order. e.g.
|
||||
|
||||
```javascript
|
||||
var engine = new Liquid({
|
||||
// relative paths will be resolved against `pwd`
|
||||
root: ['views/', 'views/partials/']
|
||||
});
|
||||
```
|
||||
|
||||
[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
|
||||
[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
|
||||
[renderFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfile
|
||||
[renderFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#renderfilesync
|
||||
[root]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#root
|
||||
|
||||
+54
-3
@@ -1,13 +1,64 @@
|
||||
LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html):
|
||||
LiquidJS is compatible to the [express template engines](https://expressjs.com/en/resources/template-engines.html). You can set liquidjs instance to the [view engine][express-views] option:
|
||||
|
||||
```javascript
|
||||
var { Liquid } = require('liquidjs');
|
||||
var engine = new Liquid();
|
||||
|
||||
// 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.
|
||||
## Template Lookup
|
||||
|
||||
The [root][root] option will continue to work as templates root, as you can see in [Render A Template File][render-a-file]. Additionally, the [`views`][express-views] option in express.js (as shown above) will also be respected. Say you have a template directory like:
|
||||
|
||||
```
|
||||
.
|
||||
├── views1/
|
||||
│ └── hello.liquid
|
||||
└── views2/
|
||||
└── world.liquid
|
||||
```
|
||||
|
||||
And you're setting template root for liquidjs to `views1` and expressjs to `views2`:
|
||||
|
||||
```javascript
|
||||
var { Liquid } = require('liquidjs');
|
||||
var engine = new Liquid({
|
||||
root: './views1/'
|
||||
});
|
||||
|
||||
app.engine('liquid', engine.express());
|
||||
app.set('views', './views2'); // specify the views directory
|
||||
app.set('view engine', 'liquid'); // set liquid to default
|
||||
```
|
||||
|
||||
Both of `hello.liquid` and `world.liquid` can be resolved and rendered:
|
||||
|
||||
```
|
||||
res.render('hello')
|
||||
res.render('world')
|
||||
```
|
||||
|
||||
## Caching
|
||||
|
||||
Simply setting the [cache option][cache] to true will enable template caching, as explained in [Caching][Caching]. It's recommended to enable cache in production environment, which can be done by:
|
||||
|
||||
```javascript
|
||||
var { Liquid } = require('liquidjs');
|
||||
var engine = new Liquid({
|
||||
cache: process.env.NODE_ENV === 'production'
|
||||
});
|
||||
```
|
||||
|
||||
[cache]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#cache
|
||||
[express-views]: http://expressjs.com/en/guide/using-template-engines.html
|
||||
[parseFile]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefile
|
||||
[parseFileSync]: https://harttle.land/liquidjs/classes/_liquid_.liquid.html#parsefilesync
|
||||
[layout]: https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout
|
||||
[include]: https://help.shopify.com/themes/liquid/tags/theme-tags#include
|
||||
[root]: https://harttle.land/liquidjs/interfaces/_liquid_options_.liquidoptions.html#root
|
||||
[render-a-file]: /harttle/liquidjs/wiki/Render-a-File
|
||||
[Caching]: /harttle/liquidjs/wiki/Caching
|
||||
|
||||
+5
-11
@@ -1,22 +1,16 @@
|
||||
* [Home](/harttle/liquidjs/wiki)
|
||||
* Tutorial
|
||||
* [Basic Usage](/harttle/liquidjs/wiki/Basic-Usage)
|
||||
* [Render a File](/harttle/liquidjs/wiki/Render-a-File)
|
||||
* [Render a Template File](/harttle/liquidjs/wiki/Render-a-File)
|
||||
* [Caching](/harttle/liquidjs/wiki/Caching)
|
||||
* [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)
|
||||
* [Plugins](/harttle/liquidjs/wiki/Plugins)
|
||||
* [Migrate to 9.0.0](/harttle/liquidjs/wiki/Migrate-to-9)
|
||||
* API
|
||||
* [API](https://harttle.github.io/liquidjs)
|
||||
* [Options](https://harttle.github.io/liquidjs/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](demo/node/)
|
||||
* Browser: [jsfiddle](https://jsfiddle.net/6u40xbzs/), [/demo/browser/](/harttle/liquidjs/blob/master/demo/browser/)
|
||||
* [Express.js Demo](/harttle/liquidjs/blob/master/demo/express/)
|
||||
* [TypeScript Demo](/harttle/liquidjs/blob/master/demo/typescript/)
|
||||
* [React JS Demo](/harttle/liquidjs/blob/master/demo/reactjs/)
|
||||
* [Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy)
|
||||
Reference in New Issue
Block a user