mirror of
https://github.com/harttle/liquidjs.git
synced 2026-09-15 04:10:40 -07:00
feat: support jekyll-like include, see #433
This commit is contained in:
Harttle
@@ -5,7 +5,7 @@ title: Include
|
||||
{% since %}v1.9.1{% endsince %}
|
||||
|
||||
{% note warn Deprecated %}
|
||||
This tag is deprecated, use <a href="./render.html">render</a> tag instead for better encapsulation.
|
||||
This tag is deprecated, use <a href="./render.html">render</a> tag instead, which contains all the features of `include` and provides better encapsulation.
|
||||
{% endnote %}
|
||||
|
||||
## Include a Template
|
||||
@@ -16,7 +16,7 @@ Renders a partial template from the template [roots][root].
|
||||
{% include 'footer.liquid' %}
|
||||
```
|
||||
|
||||
When the [extname][extname] option is set, the above `.liquid` extension can be omitted and writes:
|
||||
If [extname][extname] option is set, the above `.liquid` extension becomes optional:
|
||||
|
||||
```liquid
|
||||
{% include 'footer' %}
|
||||
@@ -44,5 +44,32 @@ A single object can be passed to a snippet by using the `with...as` syntax:
|
||||
|
||||
In the example above, the `product` variable in the partial template will hold the value of `featured_product` in the parent template.
|
||||
|
||||
## Outputs & Filters
|
||||
|
||||
When filename is specified as literal string, it supports Liquid output and filter syntax. Useful when concatenating strings for a complex filename.
|
||||
|
||||
```liquid
|
||||
{% include "prefix/{{name | append: \".html\"}}" %}
|
||||
```
|
||||
|
||||
{% note info Escaping %}
|
||||
In LiquidJS, `"` within quoted string literals need to be escaped. Adding a slash before the quote, e.g. `\"`. Using Jekyll-like filenames can make this easier, see below.
|
||||
{% endnote %}
|
||||
|
||||
## Jekyll-like filenames
|
||||
|
||||
Setting [dynamicPartials][dynamicPartials] to `false` will enable Jekyll-like includes, file names are specified as literal string. And it also supports Liquid outputs and filters.
|
||||
|
||||
```liquid
|
||||
{% include prefix/{{ page.my_variable }}/suffix %}
|
||||
```
|
||||
|
||||
This way, you don't need to escape `"` in the filename expression.
|
||||
|
||||
```liquid
|
||||
{% include prefix/{{name | append: ".html"}} %}
|
||||
```
|
||||
|
||||
[extname]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
|
||||
[root]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
|
||||
[dynamicPartials]: ../api/interfaces/liquid_options_.liquidoptions.html#dynamicPartials
|
||||
|
||||
+74
-33
@@ -4,21 +4,67 @@ title: Layout
|
||||
|
||||
{% since %}v1.9.1{% endsince %}
|
||||
|
||||
## Using a Layout Template
|
||||
## Using a Layout
|
||||
|
||||
Renders current template inside a layout template from the template [roots][root].
|
||||
Introduce a layout template for the current template to render in. The directory for layout files are defined by [layouts][layouts] or [root][root].
|
||||
|
||||
```liquid
|
||||
{% layout 'footer.liquid' %}
|
||||
// default-layout.liquid
|
||||
Header
|
||||
{% block %}{% endblock %}
|
||||
Footer
|
||||
|
||||
// page.liquid
|
||||
{% layout "default-layout.liquid" %}
|
||||
{% block %}My page content{% endblock %}
|
||||
|
||||
// result
|
||||
Header
|
||||
My page content
|
||||
Footer
|
||||
```
|
||||
|
||||
When the [extname][extname] option is set, the above `.liquid` extension can be omitted and writes:
|
||||
If [extname][extname] option is set, the `.liquid` extension becomes optional:
|
||||
|
||||
```liquid
|
||||
{% layout 'footer' %}
|
||||
{% layout 'default-layout' %}
|
||||
```
|
||||
|
||||
When a partial template is rendered by `layout`, the code inside it can access its caller's variables but its parent cannot access variables defined inside a included template.
|
||||
{% note info Scoping %}
|
||||
When a partial template is rendered by <code>layout</code>, its template have access for its caller's variables but not vice versa. Variables defined in layout will be popped out before control returning to its caller.
|
||||
{% endnote %}
|
||||
|
||||
## Multiple Blocks
|
||||
|
||||
The layout file can contain multiple blocks, each with a specified name. The following snippets yield same result as in the above example.
|
||||
|
||||
```liquid
|
||||
// default-layout.liquid
|
||||
{% block header %}{% endblock %}
|
||||
{% block content %}{% endblock %}
|
||||
{% block footer %}{% endblock %}
|
||||
|
||||
// page.liquid
|
||||
{% layout "default-layout.liquid" %}
|
||||
{% block header %}Header{% endblock %}
|
||||
{% block content %}My page content{% endblock %}
|
||||
{% block footer %}Footer{% endblock %}
|
||||
```
|
||||
|
||||
## Default Block Contents
|
||||
|
||||
In the above layout files, blocks has empty contents. But it's not necessarily be empty, in which case, the block contents in layout files will be used as default templates. The following snippets are also equivalent to the above examples:
|
||||
|
||||
```liquid
|
||||
// default-layout.liquid
|
||||
{% block header %}Header{% endblock %}
|
||||
{% block content %}{% endblock %}
|
||||
{% block footer %}Footer{% endblock %}
|
||||
|
||||
// page.liquid
|
||||
{% layout "default-layout.liquid" %}
|
||||
{% block content %}My page content{% endblock %}
|
||||
```
|
||||
|
||||
## Passing Variables
|
||||
|
||||
@@ -29,38 +75,33 @@ Variables defined in current template can be passed to a the layout template by
|
||||
{% layout 'name', my_variable: my_variable, my_other_variable: 'oranges' %}
|
||||
```
|
||||
|
||||
## Blocks
|
||||
## Outputs & Filters
|
||||
|
||||
The layout file can contain multiple `block`s which will be populated by the child template (the caller). For example we have a `default-layout.liquid` file with the following contents:
|
||||
When filename is specified as literal string, it supports Liquid output and filter syntax. Useful when concatenating strings for a complex filename.
|
||||
|
||||
```
|
||||
Header
|
||||
{% block content %}My default content{% endblock %}
|
||||
Footer
|
||||
```liquid
|
||||
{% layout "prefix/{{name | append: \".html\"}}" %}
|
||||
```
|
||||
|
||||
And it's called by a `page.liquid` file with `layout` tag:
|
||||
|
||||
```
|
||||
{% layout "default-layout" %}
|
||||
{% block content %}My page content{% endblock %}
|
||||
```
|
||||
|
||||
The render result of `page.liquid` will be :
|
||||
|
||||
```
|
||||
Header
|
||||
My page content
|
||||
Footer
|
||||
```
|
||||
|
||||
{% note tip Block %}
|
||||
<ul>
|
||||
<li>Multiple blocks can be defined within a layout template;</li>
|
||||
<li>The block name is optional when there's only one block.</li>
|
||||
<li>The block contents will fallback to parent's corresponding block if not provided by child template.</li>
|
||||
</ul>
|
||||
{% note info Escaping %}
|
||||
In LiquidJS, `"` within quoted string literals need to be escaped. Adding a slash before the quote, e.g. `\"`. Using Jekyll-like filenames can make this easier, see below.
|
||||
{% endnote %}
|
||||
|
||||
## Jekyll-like Filenames
|
||||
|
||||
Setting [dynamicPartials][dynamicPartials] to `false` will enable Jekyll-like filenames, file names are specified as literal string. And it also supports Liquid outputs and filters.
|
||||
|
||||
```liquid
|
||||
{% layout prefix/{{ page.my_variable }}/suffix %}
|
||||
```
|
||||
|
||||
This way, you don't need to escape `"` in the filename expression.
|
||||
|
||||
```liquid
|
||||
{% layout prefix/{{name | append: ".html"}} %}
|
||||
```
|
||||
|
||||
[extname]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
|
||||
[root]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
|
||||
[layouts]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-layouts
|
||||
[dynamicPartials]: ../api/interfaces/liquid_options_.liquidoptions.html#dynamicPartials
|
||||
|
||||
@@ -4,26 +4,33 @@ title: Render
|
||||
|
||||
{% since %}v9.2.0{% endsince %}
|
||||
|
||||
## Basic Usage
|
||||
## Render a Template
|
||||
|
||||
### Render a Template
|
||||
|
||||
Renders a partial template from the template [root][root]s.
|
||||
Render a partial template from partials directory specified by [partials][partials] or [root][root].
|
||||
|
||||
```liquid
|
||||
// index.liquid
|
||||
Contents
|
||||
{% render 'footer.liquid' %}
|
||||
|
||||
// footer.liquid
|
||||
Footer
|
||||
|
||||
// result
|
||||
Contents
|
||||
Footer
|
||||
```
|
||||
|
||||
When the [extname][extname] option is set, the above `.liquid` extension can be omitted and writes:
|
||||
If [extname][extname] option is set, the above `.liquid` extension becomes optional:
|
||||
|
||||
```liquid
|
||||
{% render 'footer' %}
|
||||
```
|
||||
|
||||
{% note info Variable Scope %}
|
||||
When a partial template is rendered, the code inside it can't access its parent's variables and its variables won't be accessible by its parent. This encapsulation helps make theme code easier to understand and maintain.{% endnote %}
|
||||
When a partial template is rendered, the code inside it can't access its parent's variables and its variables won't be accessible by its parent. This encapsulation makes partials easier to understand and maintain.{% endnote %}
|
||||
|
||||
### Passing Variables
|
||||
## Passing Variables
|
||||
|
||||
Variables defined in parent's scope can be passed to a the partial template by listing them as parameters on the render tag:
|
||||
|
||||
@@ -34,6 +41,32 @@ Variables defined in parent's scope can be passed to a the partial template by l
|
||||
|
||||
[globals][globals] don't need to be passed down. They are accessible from all files.
|
||||
|
||||
## Outputs & Filters
|
||||
|
||||
When filename is specified as literal string, it supports Liquid output and filter syntax. Useful when concatenating strings for a complex filename.
|
||||
|
||||
```liquid
|
||||
{% render "prefix/{{name | append: \".html\"}}" %}
|
||||
```
|
||||
|
||||
{% note info Escaping %}
|
||||
In LiquidJS, `"` within quoted string literals need to be escaped. Adding a slash before the quote, e.g. `\"`. Using Jekyll-like filenames can make this easier, see below.
|
||||
{% endnote %}
|
||||
|
||||
## Jekyll-like Filenames
|
||||
|
||||
Setting [dynamicPartials][dynamicPartials] to `false` will enable Jekyll-like filenames, file names are specified as literal string. And it also supports Liquid outputs and filters.
|
||||
|
||||
```liquid
|
||||
{% render prefix/{{ page.my_variable }}/suffix %}
|
||||
```
|
||||
|
||||
This way, you don't need to escape `"` in the filename expression.
|
||||
|
||||
```liquid
|
||||
{% render prefix/{{name | append: ".html"}} %}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### The `with` Parameter
|
||||
@@ -63,4 +96,6 @@ In the example above, the partial template will be rendered once for each `varia
|
||||
[forloop]: ./for.html
|
||||
[extname]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-extname
|
||||
[root]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-root
|
||||
[partials]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-partials
|
||||
[globals]: ../api/interfaces/liquid_options_.liquidoptions.html#Optional-globals
|
||||
[dynamicPartials]: ../api/interfaces/liquid_options_.liquidoptions.html#dynamicPartials
|
||||
|
||||
Reference in New Issue
Block a user