diff --git a/Basic-Usage.md b/Basic-Usage.md deleted file mode 100644 index 3236191..0000000 --- a/Basic-Usage.md +++ /dev/null @@ -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' -``` - diff --git a/Builtin-Tags.md b/Builtin-Tags.md index 1100f5a..632c61e 100644 --- a/Builtin-Tags.md +++ b/Builtin-Tags.md @@ -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) diff --git a/Caching.md b/Caching.md new file mode 100644 index 0000000..d5b2d9b --- /dev/null +++ b/Caching.md @@ -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 diff --git a/Get-Started.md b/Get-Started.md deleted file mode 100644 index e69de29..0000000 diff --git a/Home.md b/Home.md index 5679e07..0923b1d 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,66 @@ -Welcome to the liquidjs wiki! \ No newline at end of file +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: . You may need a [Promise polyfill][pp] for Node.js < 4 and ES5 browsers like [IE and Android UC][caniuse-promises]. + +```html + + +``` + +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 \ No newline at end of file diff --git a/Write-a-Plugin.md b/Plugins.md similarity index 92% rename from Write-a-Plugin.md rename to Plugins.md index 2bf96b5..90c5b88 100644 --- a/Write-a-Plugin.md +++ b/Plugins.md @@ -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 . 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 \ No newline at end of file +* Color Filters: https://github.com/harttle/liquidjs-color-filters + +> Feel free to add yours, this file is publicly editable. \ No newline at end of file diff --git a/Render-a-File.md b/Render-a-File.md index ad9cc93..332f20e 100644 --- a/Render-a-File.md +++ b/Render-a-File.md @@ -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 diff --git a/Use-with-Expressjs.md b/Use-with-Expressjs.md index b9e43b4..fa73577 100644 --- a/Use-with-Expressjs.md +++ b/Use-with-Expressjs.md @@ -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 diff --git a/_Sidebar.md b/_Sidebar.md index 646d867..db2c97f 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -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/) \ No newline at end of file + * [Truthy and Falsy](/harttle/liquidjs/wiki/Truthy-and-Falsy) \ No newline at end of file