From 23279a816a0582ade7f3b15c1c65c74bc147d134 Mon Sep 17 00:00:00 2001 From: Harttle Date: Sat, 18 Dec 2021 14:02:09 +0800 Subject: [PATCH] feat: support jekyll-like include, see #433 --- docs/source/tags/include.md | 31 +++++++- docs/source/tags/layout.md | 99 +++++++++++++++++------- docs/source/tags/render.md | 49 ++++++++++-- src/builtin/tags/render.ts | 17 ++-- src/parser/tokenizer.ts | 24 +++--- test/e2e/issues.ts | 16 ++++ test/integration/builtin/tags/include.ts | 24 +++++- test/integration/builtin/tags/render.ts | 26 ++++++- 8 files changed, 225 insertions(+), 61 deletions(-) diff --git a/docs/source/tags/include.md b/docs/source/tags/include.md index b9a298e4c9..19c46a243d 100644 --- a/docs/source/tags/include.md +++ b/docs/source/tags/include.md @@ -5,7 +5,7 @@ title: Include {% since %}v1.9.1{% endsince %} {% note warn Deprecated %} -This tag is deprecated, use render tag instead for better encapsulation. +This tag is deprecated, use render 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 diff --git a/docs/source/tags/layout.md b/docs/source/tags/layout.md index 1161b743f0..764eea0dd6 100644 --- a/docs/source/tags/layout.md +++ b/docs/source/tags/layout.md @@ -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 layout, 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: +{% 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 %} -``` -{% layout "default-layout" %} -{% block content %}My page content{% endblock %} -``` +## Jekyll-like Filenames -The render result of `page.liquid` will be : +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. -``` -Header -My page content -Footer +```liquid +{% layout prefix/{{ page.my_variable }}/suffix %} ``` -{% note tip Block %} - -{% endnote %} +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 diff --git a/docs/source/tags/render.md b/docs/source/tags/render.md index 537ffc284a..cddc93ba62 100644 --- a/docs/source/tags/render.md +++ b/docs/source/tags/render.md @@ -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 diff --git a/src/builtin/tags/render.ts b/src/builtin/tags/render.ts index 28bcbb5b41..b05e031679 100644 --- a/src/builtin/tags/render.ts +++ b/src/builtin/tags/render.ts @@ -92,15 +92,20 @@ export function parseFilePath (tokenizer: Tokenizer, liquid: Liquid): ParsedFile if (file.getText() === 'none') return null if (TypeGuards.isQuotedToken(file)) { // for filenames like "files/{{file}}", eval as liquid template - const tpls = liquid.parse(evalQuotedToken(file)) - // for filenames like "files/file.liquid", extract the string directly - if (tpls.length === 1 && TypeGuards.isHTMLToken(tpls[0].token)) return tpls[0].token.getContent() - return tpls + const templates = liquid.parse(evalQuotedToken(file)) + return optimize(templates) } return file } - const filepath = tokenizer.readFileName().getText() - return filepath === 'none' ? null : filepath + const tokens = [...tokenizer.readFileNameTemplate(liquid.options)] + const templates = optimize(liquid.parser.parseTokens(tokens)) + return templates === 'none' ? null : templates +} + +function optimize (templates: Template[]): string | Template[] { + // for filenames like "files/file.liquid", extract the string directly + if (templates.length === 1 && TypeGuards.isHTMLToken(templates[0].token)) return templates[0].token.getContent() + return templates } export function renderFilePath (file: ParsedFileName, ctx: Context, liquid: Liquid) { diff --git a/src/parser/tokenizer.ts b/src/parser/tokenizer.ts index 45c21fec2e..5641088311 100644 --- a/src/parser/tokenizer.ts +++ b/src/parser/tokenizer.ts @@ -33,7 +33,7 @@ export class Tokenizer { constructor ( public input: string, private trie: Trie, - private file: string = '' + public file: string = '' ) { this.N = input.length } @@ -119,15 +119,13 @@ export class Tokenizer { if (this.rawBeginAt > -1) return this.readEndrawOrRawContent(options) if (this.match(tagDelimiterLeft)) return this.readTagToken(options) if (this.match(outputDelimiterLeft)) return this.readOutputToken(options) - return this.readHTMLToken(options) + return this.readHTMLToken([tagDelimiterLeft, outputDelimiterLeft]) } - readHTMLToken (options: NormalizedFullOptions): HTMLToken { + readHTMLToken (stopStrings: string[]): HTMLToken { const begin = this.p while (this.p < this.N) { - const { tagDelimiterLeft, outputDelimiterLeft } = options - if (this.match(tagDelimiterLeft)) break - if (this.match(outputDelimiterLeft)) break + if (stopStrings.some(str => this.match(str))) break ++this.p } return new HTMLToken(this.input, begin, this.p, this.file) @@ -334,10 +332,16 @@ export class Tokenizer { return new QuotedToken(this.input, begin, this.p, this.file) } - readFileName (): IdentifierToken { - const begin = this.p - while (!(this.peekType() & BLANK) && this.peek() !== ',' && this.p < this.N) this.p++ - return new IdentifierToken(this.input, begin, this.p, this.file) + * readFileNameTemplate (options: NormalizedFullOptions): IterableIterator { + const { outputDelimiterLeft } = options + const htmlStopStrings = [',', ' ', outputDelimiterLeft] + const htmlStopStringSet = new Set(htmlStopStrings) + // break on ',' and ' ', outputDelimiterLeft only stops HTML token + while (this.p < this.N && !htmlStopStringSet.has(this.peek())) { + yield this.match(outputDelimiterLeft) + ? this.readOutputToken(options) + : this.readHTMLToken(htmlStopStrings) + } } match (word: string) { diff --git a/test/e2e/issues.ts b/test/e2e/issues.ts index f4bd002a47..e8a7698a86 100644 --- a/test/e2e/issues.ts +++ b/test/e2e/issues.ts @@ -161,4 +161,20 @@ describe('Issues', function () { const tpl = engine.parse('Welcome to {{ now | date: "%Y-%m-%d" }}!') expect(engine.render(tpl, { now: new Date('2019/02/01') })).to.eventually.equal('Welcome to 2019-02-01') }) + it('#433 Support Jekyll-like includes', async () => { + const engine = new Liquid({ + dynamicPartials: false, + root: '/tmp', + fs: { + readFileSync: (file: string) => file, + async readFile (file: string) { return `CONTENT for ${file}` }, + existsSync (file: string) { return true }, + async exists (file: string) { return true }, + resolve: (dir: string, file: string) => dir + '/' + file + } + }) + const tpl = engine.parse('{% include prefix/{{ my_variable | append: "-bar" }}/suffix %}') + const html = await engine.render(tpl, { my_variable: 'foo' }) + expect(html).to.equal('CONTENT for /tmp/prefix/foo-bar/suffix') + }) }) diff --git a/test/integration/builtin/tags/include.ts b/test/integration/builtin/tags/include.ts index b7ccc13a8e..bae15a24b9 100644 --- a/test/integration/builtin/tags/include.ts +++ b/test/integration/builtin/tags/include.ts @@ -35,6 +35,14 @@ describe('tags/include', function () { const html = await liquid.renderFile('/current.html', { name: 'foo.html' }) return expect(html).to.equal('barfoobar') }) + it('should allow escape in template string', async function () { + mock({ + '/current.html': 'bar{% include "bar/{{name | append: \\".html\\"}}" %}bar', + '/bar/foo.html': 'foo' + }) + const html = await liquid.renderFile('/current.html', { name: 'foo' }) + return expect(html).to.equal('barfoobar') + }) it('should throw when not specified', function () { mock({ @@ -155,7 +163,7 @@ describe('tags/include', function () { }) describe('static partial', function () { - it('should support filename with extention', async function () { + it('should support filename with extension', async function () { mock({ '/parent.html': 'X{% include child.html color:"red" %}Y', '/child.html': 'child with {{color}}' @@ -194,6 +202,16 @@ describe('tags/include', function () { const html = await staticLiquid.renderFile('parent.html') return expect(html).to.equal('Xchild with redY') }) + + it('should support single liquid output', async function () { + mock({ + '/parent.html': 'X{% include {{child}}, color:"red" %}Y', + '/child.html': 'child with {{color}}' + }) + const staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) + const html = await staticLiquid.renderFile('parent.html', { child: 'child.html' }) + return expect(html).to.equal('Xchild with redY') + }) }) describe('sync support', function () { it('should support quoted string', function () { @@ -204,7 +222,7 @@ describe('tags/include', function () { const html = liquid.renderFileSync('/current.html') return expect(html).to.equal('barfoobar') }) - it('should support template string', function () { + it('should support variable', function () { mock({ '/current.html': 'bar{% include name %}bar', '/bar/foo.html': 'foo' @@ -220,7 +238,7 @@ describe('tags/include', function () { const html = liquid.renderFileSync('with.html') return expect(html).to.equal('color:red, shape:rect') }) - it('should support filename with extention', function () { + it('should support filename with extension', function () { mock({ '/parent.html': 'X{% include child.html color:"red" %}Y', '/child.html': 'child with {{color}}' diff --git a/test/integration/builtin/tags/render.ts b/test/integration/builtin/tags/render.ts index 1bb6183ef7..aa769756d6 100644 --- a/test/integration/builtin/tags/render.ts +++ b/test/integration/builtin/tags/render.ts @@ -260,12 +260,15 @@ describe('tags/render', function () { }) describe('static partial', function () { + let staticLiquid: Liquid + beforeEach(() => { + staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) + }) it('should support filename with extension', async function () { mock({ '/parent.html': 'X{% render child.html color:"red" %}Y', '/child.html': 'child with {{color}}' }) - const staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) const html = await staticLiquid.renderFile('parent.html') expect(html).to.equal('Xchild with redY') }) @@ -275,7 +278,6 @@ describe('tags/render', function () { '/parent.html': 'X{% render bar/./../foo/child.html %}Y', '/foo/child.html': 'child' }) - const staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) const html = await staticLiquid.renderFile('parent.html') expect(html).to.equal('XchildY') }) @@ -285,7 +287,6 @@ describe('tags/render', function () { '/parent.html': 'X{% render foo/child.html %}Y', '/foo/child.html': 'child' }) - const staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) const html = await staticLiquid.renderFile('parent.html') expect(html).to.equal('XchildY') }) @@ -295,10 +296,27 @@ describe('tags/render', function () { '/parent.html': 'X{% render child.html, color:"red" %}Y', '/child.html': 'child with {{color}}' }) - const staticLiquid = new Liquid({ dynamicPartials: false, root: '/' }) const html = await staticLiquid.renderFile('parent.html') expect(html).to.equal('Xchild with redY') }) + + it('should support template string', async function () { + mock({ + '/current.html': 'bar{% render bar/{{name}} %}bar', + '/bar/foo.html': 'foo' + }) + const html = await staticLiquid.renderFile('/current.html', { name: 'foo.html' }) + expect(html).to.equal('barfoobar') + }) + + it('should support filters in template string', async function () { + mock({ + '/current.html': 'bar{% render bar/{{name | append: ".html"}} %}bar', + '/bar/foo.html': 'foo' + }) + const html = await staticLiquid.renderFile('/current.html', { name: 'foo' }) + expect(html).to.equal('barfoobar') + }) }) describe('sync support', function () { it('should support quoted string', function () {