mirror of
https://github.com/harttle/liquidjs.git
synced 2026-09-18 14:00:39 -07:00
docs: add tutorials/options.md
This commit is contained in:
harttle
@@ -18,7 +18,7 @@
|
||||
en: 'Memory Optimization: a more elaborate parser reducing the memory footprint by 57.7%.'
|
||||
-
|
||||
url: https://github.com/harttle/liquidjs/pull/205
|
||||
date: '2016-09-15'
|
||||
date: '2020-09-15'
|
||||
title:
|
||||
zh-cn: '性能提升：引入 AST 并重新设计 Token 类型系统，使渲染性能平均提升 100.3%。'
|
||||
en: 'Performance Boost: a simple AST to improve render performance by 100.3%.'
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
tutorials:
|
||||
getting_started:
|
||||
intro: intro-to-liquid.html
|
||||
setup: setup.html
|
||||
syntax: syntax.html
|
||||
options: options.html
|
||||
render_file: render-file.html
|
||||
partials: partials-and-layouts.html
|
||||
express: use-in-expressjs.html
|
||||
@@ -14,6 +15,7 @@ tutorials:
|
||||
truth: truthy-and-falsy.html
|
||||
miscellaneous:
|
||||
migration9: migrate-to-9.html
|
||||
changelog: changelog.html
|
||||
contribution_guidelines: contribution-guidelines.html
|
||||
|
||||
filters:
|
||||
|
||||
@@ -8,22 +8,22 @@ ul#intro-feature-list
|
||||
.intro-feature-icon
|
||||
i.icon-shield
|
||||
h3.intro-feature-title Safe Rendering
|
||||
p.intro-feature-desc All outputs are automatically escaped for safe and customer facing HTML rendering. Operators and expressions are parsed to AST and no #[code eval] or #[code new Function] are used.
|
||||
p.intro-feature-desc Liquid templates are highly readable and fault-tolerant thus suitable for designers and customers. Operators and expressions are parsed to AST and no #[code eval] or #[code new Function] are used.
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
.intro-feature-icon
|
||||
i.icon-javascript
|
||||
h3.intro-feature-title Pure JavaScript
|
||||
p.intro-feature-desc Written with zero npm dependencies and no native bindings, available for both Node.js and the browsers. All of the CMD, ESM and CJS bundles are available on CDN.
|
||||
i.icon-rocket
|
||||
h3.intro-feature-title Zero Dependency
|
||||
p.intro-feature-desc Written with zero npm dependency and no native binding, available in both Node.js and browsers. All of the CMD, ESM and CJS bundles are available on CDN.
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
.intro-feature-icon
|
||||
i.icon-shopify
|
||||
h3.intro-feature-title Shopify Compatible
|
||||
p.intro-feature-desc Almost all features, filters and tags from Ruby #[a(href="https://github.com/shopify/liquid") shopify/liquid] are also supported by LiquidJS. #[a(href="https://jekyllrb.com/") Jekyll sites], #[a(href="https://pages.github.com/") Github Pages] and #[a(href="https://themes.shopify.com/") Shopify templates] can be ported to Node.js without pain.
|
||||
p.intro-feature-desc All filters and tags from Ruby #[a(href="https://github.com/shopify/liquid") shopify/liquid] are supported by LiquidJS. #[a(href="https://jekyllrb.com/") Jekyll sites], #[a(href="https://pages.github.com/") Github Pages] and #[a(href="https://themes.shopify.com/") Shopify templates] can be ported to Node.js without pain.
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
.intro-feature-icon
|
||||
i.icon-cog
|
||||
h3.intro-feature-title Extensibility
|
||||
p.intro-feature-desc The whole repo is re-written in TypeScript strict mode to ensure the APIs are consistent and the documentation is always up to date. Apart from 60+ builtin tags and filters, LiquidJS provides APIs to register yours.
|
||||
i.icon-typescript
|
||||
h3.intro-feature-title TypeScript Strict
|
||||
p.intro-feature-desc The whole repo is re-written in TypeScript strict mode to ensure a smooth experience using this lib and the document is precise and always up to date.
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Options
|
||||
---
|
||||
|
||||
The [Liquid][liquid] constructor accepts a plain object as options to define the behaviour of LiquidJS. All of these options are optional thus we can specify any of them, for example the `cache` option:
|
||||
|
||||
```javascript
|
||||
const { Liquid } = require('liquidjs')
|
||||
const engine = new Liquid({
|
||||
cache: true
|
||||
})
|
||||
```
|
||||
|
||||
{% note info API Document %}
|
||||
Following is an overview for all the options, for exact types and signatures please refer to <a href="https://liquidjs.com/api/interfaces/liquid_options_.liquidoptions.html" target="_self">LiquidOptions | API</a>.
|
||||
{% endnote %}
|
||||
|
||||
## cache
|
||||
|
||||
**cache** is used to improve performance by caching previously parsed template structures, specially in cases when we're repeatedly parse or render files.
|
||||
|
||||
It's default to `false`. When setting to `true` a default LRU cache of size 1024 will be enabled. And certainly it can be a number which indicates the size of cache you want.
|
||||
|
||||
Additionally, it can also be a custom cache implementation. See [Caching][caching] for details.
|
||||
|
||||
## dynamicPartials
|
||||
|
||||
**dynamicPartials** indicates whether or not to treat filename arguments in [include][include], [render][render], [layout][layout] tags as a variable. Defaults to `true`. For example, render the following snippet with scope `{ file: 'foo.html' }` will include the `foo.html`:
|
||||
|
||||
```liquid
|
||||
{% include file %}
|
||||
```
|
||||
|
||||
Setting `dynamicPartials: false`, LiquidJS will try to include the file named `file`, which is weird but allows simpler syntax if your template relations are static:
|
||||
|
||||
```liquid
|
||||
{% liquid foo.html %}
|
||||
```
|
||||
|
||||
{% note warn Common Pitfall %}
|
||||
LiquidJS defaults this option to <code>true</code> to be compatible with shopify/liquid, but if you're from <a href="https://github.com/11ty/eleventy" target="_blank">eleventy</a> it's set to <code>false</code> by default (see <a href="https://www.11ty.dev/docs/languages/liquid/#quoted-include-paths" target="_blank">Quoted Include Paths</a>) which I believe is trying to be compatible with Jekyll.{% endnote %}
|
||||
|
||||
## extname
|
||||
|
||||
**extname** defines the default extname to be appended into filenames if the filename has no extname. Defaults to `''` which means it's disabled by default. By setting it to `.liquid`:
|
||||
|
||||
```liquid
|
||||
{% render "foo" %} loads foo.liquid
|
||||
{% render "foo.html" %} loads foo.html
|
||||
```
|
||||
|
||||
{% note info Legacy Versions %}
|
||||
Before 2.0.1, <code>extname</code> is set to `.liquid` by default. To change that you need to set <code>extname: ''</code> explicitly. See <a href="https://github.com/harttle/liquidjs/issues/41" target="_blank">#41</a> for details.
|
||||
{% endnote %}
|
||||
|
||||
## root
|
||||
|
||||
**root** is used to specify template directories for LiquidJS to lookup and read template files. Can be a single string and an array of strings. See [Render Files][render-file] for details.
|
||||
|
||||
## fs
|
||||
|
||||
**fs** is used to define a custom file system implementation which will be used by LiquidJS to lookup and read template files. See [Abstract File System][abstract-fs] for details.
|
||||
|
||||
## globals
|
||||
|
||||
**globals** is used to define global variables available to all templates even in cases of [render tag][render]. See [3185][185] for details.
|
||||
|
||||
## Trimming
|
||||
|
||||
**greedy**, **trimOutputLeft**, **trimOutputRight**, **trimTagLeft**, **trimTagRight** options are used to eliminate extra newlines and indents in templates arround Liquid Constructs. See [Whitespace Control][wc] for details.
|
||||
|
||||
## Delimiter
|
||||
|
||||
**outputDelimiterLeft**, **outputDelimiterRight**, **tagDelimiterLeft**, **tagDelimiterRight** are used to customize the delimiters for LiquidJS [Tags and Filters][intro]. For example with `outputDelimiterLeft: <%=, outputDelimiterRight: %>` we are able to avoid conflicts with other languages:
|
||||
|
||||
```ejs
|
||||
<%= username | append: ", welcome to LiquidJS!" %>
|
||||
```
|
||||
|
||||
## Strict
|
||||
|
||||
**strictFilters** is used to assert filter existence. If set to `false`, undefined filters will be skipped. Otherwise, undefined filters will cause a parse exception. Defaults to `false`.
|
||||
|
||||
**strictVariables** is used to assert variable existence. If set to `false`, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause a render exception. Defaults to `false`.
|
||||
|
||||
{% note info Non-existent Tags %}
|
||||
Non-existent tags always throw errors during pasrsing and this behaviour can not be customized.
|
||||
{% endnote %}
|
||||
|
||||
[liquid]: ../api/classes/liquid_.liquid.html
|
||||
[caching]: ./caching.html
|
||||
[abstract-fs]: ./render-file.html#Abstract-File-System
|
||||
[render-file]: ./render-file.html
|
||||
[185]: https://github.com/harttle/liquidjs/issues/185
|
||||
[render]: ../tags/render.html
|
||||
[include]: ../tags/include.html
|
||||
[layout]: ../tags/layout.html
|
||||
[wc]: ./whitespace-control.html
|
||||
[intro]: ./intro-to-liquid.html
|
||||
@@ -8,12 +8,12 @@ ul#intro-feature-list
|
||||
.intro-feature-icon
|
||||
i.icon-shield
|
||||
h3.intro-feature-title 安全渲染
|
||||
p.intro-feature-desc 所有输出都默认经过转义，可以安全地开放给客户使用。运算符和表达式都先解析到 AST 再去渲染，避免了 #[code eval] 和 #[code new Function]。
|
||||
p.intro-feature-desc Liquid 模板有很强的可读性和容错性，适用于开放给设计师和客户。运算符和表达式都先解析到 AST 再去渲染，避免了 #[code eval] 和 #[code new Function]。
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
.intro-feature-icon
|
||||
i.icon-javascript
|
||||
h3.intro-feature-title 纯 JavaScript
|
||||
i.icon-rocket
|
||||
h3.intro-feature-title 零依赖
|
||||
p.intro-feature-desc 零 NPM 依赖且没有 Native 绑定的 Liquid 实现，Node.js 和浏览器通用。同时提供了 CDN 可用的 CMD, ESM 和 CJS 打包。
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
@@ -24,6 +24,6 @@ ul#intro-feature-list
|
||||
li.intro-feature-wrap
|
||||
.intro-feature
|
||||
.intro-feature-icon
|
||||
i.icon-cog
|
||||
h3.intro-feature-title Extensibility
|
||||
p.intro-feature-desc 整个项目在 TypeScript strict 模式下重写，确保了一致的 API 和实时更新的文档。除了 60+ 内置标签和过滤器之外，LiquidJS 还提供了 API 来注册你自己的插件。
|
||||
i.icon-typescript
|
||||
h3.intro-feature-title TypeScript
|
||||
p.intro-feature-desc 整个项目在 TypeScript strict 模式下重写，让这个库拥有顺滑的使用体验，同时确保了一致的 API 和实时的、精确的文档。
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: 选项
|
||||
---
|
||||
|
||||
[Liquid][liquid] 构造函数接受一个参数对象，用来定义各种模板引擎行为。这些参数都是可选的，比如我可以指定其中一个参数 `cache`：
|
||||
|
||||
```javascript
|
||||
const { Liquid } = require('liquidjs')
|
||||
const engine = new Liquid({
|
||||
cache: true
|
||||
})
|
||||
```
|
||||
|
||||
{% note info API 文档 %}
|
||||
下面的所有选项的概述，希望了解具体的类型和签名，请前往 <a href="https://liquidjs.com/api/interfaces/liquid_options_.liquidoptions.html" target="_self">LiquidOptions | API</a>.
|
||||
{% endnote %}
|
||||
|
||||
## cache
|
||||
|
||||
**cache** 用来指定是否缓存曾经读取和处理过的模板来提升性能。在生产环境模板会重复渲染的情况会很有用。
|
||||
|
||||
默认是 `false`，当设置为 `true` 时会启用一个大小为 1024 的 LRU 缓存。当然也可以传一个数字来指定缓存大小。此外还可以是一个自定义的缓存实现，LiquidJS 会通过它来查找和读写文件。详情请参考 [Caching][caching]。
|
||||
|
||||
## dynamicPartials
|
||||
|
||||
**dynamicPartials** 表示是否把传给 [include][include], [render][render], [layout][layout] 标签的文件名当做变量处理。默认为 `true`。例如用上下文 `{ file: 'foo.html' }` 渲染下面的模板将会引入文件 `foo.html`：
|
||||
|
||||
```liquid
|
||||
{% include file %}
|
||||
```
|
||||
|
||||
设置 `dynamicPartials: false` 后 LiquidJS 将会尝试去读取 `file`。当你的模板之间都是静态引入关系时会很有用：
|
||||
|
||||
```liquid
|
||||
{% liquid foo.html %}
|
||||
```
|
||||
|
||||
{% note warn Common Pitfall %}
|
||||
LiquidJS 把这个选项默认值设为 <code>true</code> 以兼容于 shopify/liquid，但如果你在使用 <a href="https://github.com/11ty/eleventy" target="_blank">eleventy</a> 它会设置默认值 <code>false</code> （参考 <a href="https://www.11ty.dev/docs/languages/liquid/#quoted-include-paths" target="_blank">Quoted Include Paths</a>）以兼容于 Jekyll。{% endnote %}
|
||||
|
||||
## extname
|
||||
|
||||
**extname** 定义了默认的文件后缀，当传入文件名不包含后缀时自动追加。默认值是 `''` 也就是说默认是禁用的。如果设置为 `.liquid`：
|
||||
|
||||
```liquid
|
||||
{% render "foo" %} 会加载 foo.liquid
|
||||
{% render "foo.html" %} 会加载 foo.html
|
||||
```
|
||||
|
||||
{% note info Legacy Versions %}
|
||||
在 2.0.1 之前，<code>extname</code> 默认值为 `.liquid`。要禁用它需要明确设置为 <code>extname: ''</code>。详情参考 <a href="https://github.com/harttle/liquidjs/issues/41" target="_blank">#41</a>。
|
||||
{% endnote %}
|
||||
|
||||
## root
|
||||
|
||||
**root** 用来指定 LiquidJS 查找和读取模板的根目录。可以是单个字符串，也可以是一个数组 LiquidJS 会顺序查找。详情请参考 [Render Files][render-file]。
|
||||
|
||||
## fs
|
||||
|
||||
**fs** 用来自定义文件系统实现，详情请参考 [Abstract File System][abstract-fs]。
|
||||
|
||||
## globals
|
||||
|
||||
**globals** 用来定义对所有模板可见的全局变量。包括 [render tag][render] 引入的子模板，见 [3185][185]。
|
||||
|
||||
## 换行和缩进
|
||||
|
||||
**greedy**, **trimOutputLeft**, **trimOutputRight**, **trimTagLeft**, **trimTagRight** 选项用来移除 Liquid 语法周围的换行和缩进，详情请参考 [Whitespace Control][wc]。
|
||||
|
||||
## 自定义分隔符
|
||||
|
||||
**outputDelimiterLeft**, **outputDelimiterRight**, **tagDelimiterLeft**, **tagDelimiterRight** 用来自定义 LiquidJS 中 [标签和过滤器][intro] 的分隔符。例如设置了 `outputDelimiterLeft: <%=, outputDelimiterRight: %>` 后我们可以避免跟其他模板引擎冲突：
|
||||
|
||||
```ejs
|
||||
<%= username | append: ", welcome to LiquidJS!" %>
|
||||
```
|
||||
|
||||
## 严格模式
|
||||
|
||||
**strictFilters** 用来启用过滤器的严格模式，如果设置为 `true` 过滤器不存在时解析会抛出异常。默认为 `false`，这时会跳过不存在的过滤器。
|
||||
|
||||
**strictVariables** 用来启用变量严格模式。如果设置为 `true` 变量不存在时渲染会抛出异常，默认为 `false` 这时不存在的变量会被渲染为空字符串。
|
||||
|
||||
{% note info 不存在的标签 %}
|
||||
不存在的标签总是会抛出一个解析异常，这一行为无法自定义。
|
||||
{% endnote %}
|
||||
|
||||
[liquid]: ../api/classes/liquid_.liquid.html
|
||||
[caching]: ./caching.html
|
||||
[abstract-fs]: ./render-file.html#Abstract-File-System
|
||||
[render-file]: ./render-file.html
|
||||
[185]: https://github.com/harttle/liquidjs/issues/185
|
||||
[render]: ../tags/render.html
|
||||
[include]: ../tags/include.html
|
||||
[layout]: ../tags/layout.html
|
||||
[wc]: ./whitespace-control.html
|
||||
[intro]: ./intro-to-liquid.html
|
||||
Reference in New Issue
Block a user