mirror of
https://github.com/harttle/liquidjs.git
synced 2026-09-17 05:10:40 -07:00
Deploying to gh-pages from @ harttle/liquidjs@292a93b738 🚀
This commit is contained in:
harttle
@@ -93,10 +93,19 @@
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>As covered in <a href="/tutorials/register-filters-tags.html">Register Filters/Tags</a>, we can access filter arguments directly in filter function like:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {{ 1 | add: 2, 3 }}</span></span><br><span class="line"><span class="comment">// Output: 6</span></span><br><span class="line">engine.<span class="title function_">registerFilter</span>(<span class="string">'add'</span>, <span class="function">(<span class="params">initial, arg1, arg2</span>) =></span> initial + arg1 + arg2)</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: {{ 1 | add: 2, 3 }}</span>
|
||||
<span class="token comment">// Output: 6</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'add'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">initial<span class="token punctuation">,</span> arg1<span class="token punctuation">,</span> arg2</span><span class="token punctuation">)</span> <span class="token operator">=></span> initial <span class="token operator">+</span> arg1 <span class="token operator">+</span> arg2<span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>When it comes to stateful filters, for example transform a URL path to full URL, we’ll need to access a <code>origin</code> in current scope:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {{ '/index.html' | fullURL }}</span></span><br><span class="line"><span class="comment">// Scope: { origin: "https://liquidjs.com" }</span></span><br><span class="line"><span class="comment">// Output: https://liquidjs.com/index.html</span></span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerFilter</span>(<span class="string">'fullURL'</span>, <span class="keyword">function</span> (<span class="params">path</span>) {</span><br><span class="line"> <span class="keyword">const</span> origin = <span class="variable language_">this</span>.<span class="property">context</span>.<span class="title function_">get</span>([<span class="string">'origin'</span>])</span><br><span class="line"> <span class="keyword">return</span> <span class="keyword">new</span> <span class="title function_">URL</span>(path, origin).<span class="title function_">toString</span>() </span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: {{ '/index.html' | fullURL }}</span>
|
||||
<span class="token comment">// Scope: { origin: "https://liquidjs.com" }</span>
|
||||
<span class="token comment">// Output: https://liquidjs.com/index.html</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'fullURL'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">path</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> origin <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>context<span class="token punctuation">.</span><span class="token function">get</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string">'origin'</span><span class="token punctuation">]</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">URL</span><span class="token punctuation">(</span>path<span class="token punctuation">,</span> origin<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">toString</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>See this JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/ctj364up/1/">https://jsfiddle.net/ctj364up/1/</a></p>
|
||||
<blockquote class="note warn"><strong class="note-title">Arrow Functions</strong><p><code>this</code> in arrow functions is bound to current JavaScript context, you’ll need to use <code>function(){}</code> instead of <code>()=>{}</code> syntax to access <code>this.context</code> correctly.</p>
|
||||
@@ -105,7 +114,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="register-filters-tags.html" class="article-footer-prev" title="Register Filters/Tags"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="parse-parameters.html" class="article-footer-next" title="Parse Parameters"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+19
-4
@@ -96,19 +96,34 @@
|
||||
<p>LiquidJS provides multiple ways to cache the parsed templates to improve performance.</p>
|
||||
<h2 id="Programmatically" class="article-heading"><a href="#Programmatically" class="headerlink" title="Programmatically"></a>Programmatically<a class="article-anchor" href="#Programmatically" aria-hidden="true"></a></h2><p>The <a href="/api/classes/Liquid.html#parse">.parse()</a>, <a href="/api/classes/Liquid.html#parseFile">.parseFile()</a>, <a href="/api/classes/Liquid.html#parseFileSync">.parseFileSync()</a> APIs are used to parse templates from string or files. The result template can be then rendered multiple times with different context.</p>
|
||||
<p>Parse from string:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> tpl = engine.<span class="title function_">parse</span>(<span class="string">'{{name | capitalize}}'</span>);</span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">renderSync</span>(tpl, {<span class="attr">name</span>: <span class="string">'alice'</span>}) <span class="comment">// 'Alice'</span></span><br><span class="line">engine.<span class="title function_">renderSync</span>(tpl, {<span class="attr">name</span>: <span class="string">'bob'</span>}) <span class="comment">// 'Bob'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> tpl <span class="token operator">=</span> engine<span class="token punctuation">.</span><span class="token function">parse</span><span class="token punctuation">(</span><span class="token string">'{{name | capitalize}}'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderSync</span><span class="token punctuation">(</span>tpl<span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token comment">// 'Alice'</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderSync</span><span class="token punctuation">(</span>tpl<span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'bob'</span><span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token comment">// 'Bob'</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Parse from file:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> tpl = engine.<span class="title function_">parseFileSync</span>(<span class="string">'hello'</span>); <span class="comment">// contents of `hello.liquid`: {{name}}</span></span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">renderSync</span>(tpl, {<span class="attr">name</span>: <span class="string">'alice'</span>}) <span class="comment">// 'Alice'</span></span><br><span class="line">engine.<span class="title function_">renderSync</span>(tpl, {<span class="attr">name</span>: <span class="string">'bob'</span>}) <span class="comment">// 'Bob'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> tpl <span class="token operator">=</span> engine<span class="token punctuation">.</span><span class="token function">parseFileSync</span><span class="token punctuation">(</span><span class="token string">'hello'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// contents of `hello.liquid`: {{name}}</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderSync</span><span class="token punctuation">(</span>tpl<span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token comment">// 'Alice'</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderSync</span><span class="token punctuation">(</span>tpl<span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'bob'</span><span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token comment">// 'Bob'</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>The template string/file is parsed only once and rendered multiple times using different context. Templates for different files can be stored into a <code>Map</code> and can be retrieved directly for subsequent renders.</p>
|
||||
<h2 id="The-cache-Option" class="article-heading"><a href="#The-cache-Option" class="headerlink" title="The cache Option"></a>The <code>cache</code> Option<a class="article-anchor" href="#The-cache-Option" aria-hidden="true"></a></h2><p>The <a href="/api/interfaces/LiquidOptions.html#cache">cache option</a> can be set to instruct liquidjs to use cached parsed templates each time you call <a href="/api/classes/Liquid.html#renderFile">renderFile</a> or <a href="/api/classes/Liquid.html#renderFileSync">renderFileSync</a>.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>);</span><br><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">cache</span>: <span class="literal">true</span></span><br><span class="line">});</span><br><span class="line"></span><br><span class="line"><span class="comment">// liquidjs parses the hello.liquid, then renders it with {name: 'alice'}</span></span><br><span class="line">engine.<span class="title function_">renderFileSync</span>(<span class="string">'hello'</span>, {<span class="attr">name</span>: <span class="string">'alice'</span>})</span><br><span class="line"></span><br><span class="line"><span class="comment">// liquidjs finds the cached template, then renders it with {name: 'bob'}</span></span><br><span class="line">engine.<span class="title function_">renderFileSync</span>(<span class="string">'hello'</span>, {<span class="attr">name</span>: <span class="string">'bob'</span>})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">cache</span><span class="token operator">:</span> <span class="token boolean">true</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">// liquidjs parses the hello.liquid, then renders it with {name: 'alice'}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderFileSync</span><span class="token punctuation">(</span><span class="token string">'hello'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
|
||||
<span class="token comment">// liquidjs finds the cached template, then renders it with {name: 'bob'}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderFileSync</span><span class="token punctuation">(</span><span class="token string">'hello'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'bob'</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="use-in-expressjs.html" class="article-footer-prev" title="Use in Express.js"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="escaping.html" class="article-footer-next" title="Escaping"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -746,7 +746,7 @@
|
||||
</script></li></ul>
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:37:03.734Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:42.372Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="migrate-to-9.html" class="article-footer-prev" title="Migrate to LiquidJS 9"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="differences.html" class="article-footer-next" title="Differences with Shopify/liquid"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -102,7 +102,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="differences.html" class="article-footer-prev" title="Differences with Shopify/liquid"><i class="icon-chevron-left"></i><span>Prev</span></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -126,7 +126,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="changelog.html" class="article-footer-prev" title="Changelog"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="contribution-guidelines.html" class="article-footer-next" title="Contribution Guidelines"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+13
-4
@@ -94,24 +94,33 @@
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>When the template or data context cannot be trusted, enabling DoS prevention options is crucial. LiquidJS provides 3 options for this purpose: <code>parseLimit</code>, <code>renderLimit</code>, and <code>memoryLimit</code>.</p>
|
||||
<h2 id="TL-DR" class="article-heading"><a href="#TL-DR" class="headerlink" title="TL;DR"></a>TL;DR<a class="article-anchor" href="#TL-DR" aria-hidden="true"></a></h2><p>Setting these options can largely ensure that your LiquidJS instance won’t hang for extended periods or consume excessive memory. These limits are based on the available JavaScript APIs, so they are not precise hard limits but thresholds to help prevent your process from failing or hanging.</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> liquid = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">parseLimit</span>: <span class="number">1e8</span>, <span class="comment">// typical size of your templates in each render</span></span><br><span class="line"> <span class="attr">renderLimit</span>: <span class="number">1000</span>, <span class="comment">// limit each render to be completed in 1s</span></span><br><span class="line"> <span class="attr">memoryLimit</span>: <span class="number">1e9</span>, <span class="comment">// memory available for LiquidJS (1e9 for 1GB)</span></span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">const</span> liquid <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
parseLimit<span class="token operator">:</span> <span class="token number">1e8</span><span class="token punctuation">,</span> <span class="token comment">// typical size of your templates in each render</span>
|
||||
renderLimit<span class="token operator">:</span> <span class="token number">1000</span><span class="token punctuation">,</span> <span class="token comment">// limit each render to be completed in 1s</span>
|
||||
memoryLimit<span class="token operator">:</span> <span class="token number">1e9</span><span class="token punctuation">,</span> <span class="token comment">// memory available for LiquidJS (1e9 for 1GB)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>When a <code>parse()</code> or <code>render()</code> cannot be completed within given resource, it throws.</p>
|
||||
<h2 id="parseLimit" class="article-heading"><a href="#parseLimit" class="headerlink" title="parseLimit"></a>parseLimit<a class="article-anchor" href="#parseLimit" aria-hidden="true"></a></h2><p><a href="/api/interfaces/LiquidOptions.html#parseLimit">parseLimit</a> restricts the size (character length) of templates parsed in each <code>.parse()</code> call, including referenced partials and layouts. Since LiquidJS parses template strings in near O(n) time, limiting total template length is usually sufficient.</p>
|
||||
<p>A typical PC handles <code>1e8</code> (100M) characters without issues.</p>
|
||||
<h2 id="renderLimit" class="article-heading"><a href="#renderLimit" class="headerlink" title="renderLimit"></a>renderLimit<a class="article-anchor" href="#renderLimit" aria-hidden="true"></a></h2><p>Restricting template size alone is insufficient because dynamic loops with large counts can occur in render time. <a href="/api/interfaces/LiquidOptions.html#renderLimit">renderLimit</a> mitigates this by limiting the time consumed by each <code>render()</code> call.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{%- for i in (1..10000000) -%}</span><br><span class="line"> order: {{i}}</span><br><span class="line">{%- endfor -%}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%-</span> <span class="token keyword">for</span> i <span class="token keyword">in</span> <span class="token punctuation">(</span><span class="token number">1</span><span class="token range operator">..</span><span class="token number">10000000</span><span class="token punctuation">)</span> <span class="token delimiter punctuation">-%}</span></span>
|
||||
order: <span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span>i<span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%-</span> <span class="token keyword">endfor</span> <span class="token delimiter punctuation">-%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Render time is checked on a per-template basis (before rendering each template). In the above example, there are 2 templates in the loop: <code>order:</code> and <code>{{i}}</code>, render time will be checked 10000000x2 times.</p>
|
||||
<p>For time-consuming tags and filters within a single template, the process can still hang. For fully controlled rendering, consider using a process manager like <a target="_blank" rel="noopener external nofollow noreferrer" href="https://www.npmjs.com/package/paralleljs">paralleljs</a>.</p>
|
||||
<h2 id="memoryLimit" class="article-heading"><a href="#memoryLimit" class="headerlink" title="memoryLimit"></a>memoryLimit<a class="article-anchor" href="#memoryLimit" aria-hidden="true"></a></h2><p>Even with small number of templates and iterations, memory usage can grow exponentially. In the following example, memory doubles with each iteration:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">{% assign array = "1,2,3" | split: "," %}</span><br><span class="line">{% for i in (1..32) %}</span><br><span class="line"> {% assign array = array | concat: array %}</span><br><span class="line">{% endfor %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">assign</span> array <span class="token operator">=</span> <span class="token string">"1,2,3"</span> <span class="token operator">|</span> <span class="token function filter">split</span><span class="token operator">:</span> <span class="token string">","</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">for</span> i <span class="token keyword">in</span> <span class="token punctuation">(</span><span class="token number">1</span><span class="token range operator">..</span><span class="token number">32</span><span class="token punctuation">)</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">assign</span> array <span class="token operator">=</span> array <span class="token operator">|</span> <span class="token function filter">concat</span><span class="token operator">:</span> array <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endfor</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p><a href="/api/interfaces/LiquidOptions.html#memoryLimit">memoryLimit</a> restricts memory-sensitive filters to prevent excessive memory allocation. As <a target="_blank" rel="noopener external nofollow noreferrer" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_management">JavaScript uses GC to manage memory</a>, <code>memoryLimit</code> limits only the total number of objects allocated by memory sensitive filters in LiquidJS thus may not reflect the actual memory footprint.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="truthy-and-falsy.html" class="article-footer-prev" title="Truthy and Falsy"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="migrate-to-9.html" class="article-footer-next" title="Migrate to LiquidJS 9"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+106
-10
@@ -96,7 +96,23 @@
|
||||
<blockquote class="note info"><strong class="note-title">Drop for JavaScript</strong><p><em>Drop</em> interface is implemented differently in LiquidJS compared to built-in filters and other template functionalities. Since LiquidJS runs in JavaScript, custom Drops need to be reimplemented in JavaScript anyway. There’s no compatibility between JavaScript classes and Ruby classes.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Basic-Usage" class="article-heading"><a href="#Basic-Usage" class="headerlink" title="Basic Usage"></a>Basic Usage<a class="article-anchor" href="#Basic-Usage" aria-hidden="true"></a></h2><figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">SettingsDrop</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Drop</span> {</span><br><span class="line"> <span class="title function_">constructor</span>(<span class="params"></span>) {</span><br><span class="line"> <span class="variable language_">super</span>()</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">foo</span> = <span class="string">'FOO'</span></span><br><span class="line"> }</span><br><span class="line"> <span class="title function_">bar</span>(<span class="params"></span>) {</span><br><span class="line"> <span class="keyword">return</span> <span class="string">'BAR'</span></span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="keyword">const</span> template = <span class="string">`foo: {{settings.foo}}, bar: {{settings.bar}}`</span></span><br><span class="line"><span class="keyword">const</span> context = { <span class="attr">settings</span>: <span class="keyword">new</span> <span class="title class_">SettingsDrop</span>() }</span><br><span class="line"><span class="comment">// Outputs: "foo: FOO, bar: BAR"</span></span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(template, context).<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<h2 id="Basic-Usage" class="article-heading"><a href="#Basic-Usage" class="headerlink" title="Basic Usage"></a>Basic Usage<a class="article-anchor" href="#Basic-Usage" aria-hidden="true"></a></h2><pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">SettingsDrop</span> <span class="token keyword">extends</span> <span class="token class-name">Drop</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">constructor</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>foo <span class="token operator">=</span> <span class="token string">'FOO'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token function">bar</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token string">'BAR'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> template <span class="token operator">=</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">foo: {{settings.foo}}, bar: {{settings.bar}}</span><span class="token template-punctuation string">`</span></span>
|
||||
<span class="token keyword">const</span> context <span class="token operator">=</span> <span class="token punctuation">{</span> <span class="token literal-property property">settings</span><span class="token operator">:</span> <span class="token keyword">new</span> <span class="token class-name">SettingsDrop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span>
|
||||
<span class="token comment">// Outputs: "foo: FOO, bar: BAR"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span>template<span class="token punctuation">,</span> context<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p><a target="_blank" rel="noopener external nofollow noreferrer" href="https://runkit.com/embed/2is7di4mc7kk">Runkit link</a></p>
|
||||
<p>As shown above, besides reading properties from context scopes, you can also call methods. You only need to create a custom class inherited from <code>Drop</code>.</p>
|
||||
@@ -104,19 +120,93 @@
|
||||
</blockquote>
|
||||
|
||||
<h2 id="liquidMethodMissing" class="article-heading"><a href="#liquidMethodMissing" class="headerlink" title="liquidMethodMissing"></a>liquidMethodMissing<a class="article-anchor" href="#liquidMethodMissing" aria-hidden="true"></a></h2><p>For cases when there isn’t a fixed set of properties, you can leverage <code>liquidMethodMissing</code> to dynamically resolve the value of a variable name.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">SettingsDrop</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Drop</span> {</span><br><span class="line"> <span class="title function_">liquidMethodMissing</span>(<span class="params">key</span>) {</span><br><span class="line"> <span class="keyword">return</span> key.<span class="title function_">toUpperCase</span>()</span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="comment">// Outputs: "COO"</span></span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(<span class="string">"{{settings.coo}}"</span>, { <span class="attr">settings</span>: <span class="keyword">new</span> <span class="title class_">SettingsDrop</span>() })</span><br><span class="line"> .<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">SettingsDrop</span> <span class="token keyword">extends</span> <span class="token class-name">Drop</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">liquidMethodMissing</span><span class="token punctuation">(</span><span class="token parameter">key</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> key<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// Outputs: "COO"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">"{{settings.coo}}"</span><span class="token punctuation">,</span> <span class="token punctuation">{</span> <span class="token literal-property property">settings</span><span class="token operator">:</span> <span class="token keyword">new</span> <span class="token class-name">SettingsDrop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p><code>liquidMethodMissing</code> supports Promise, meaning you can make async calls within it. A more useful case can be fetching the value dynamically from the database. By using Drops, you can avoid hardcoding each property into the context. For example:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">DBDrop</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Drop</span> {</span><br><span class="line"> <span class="keyword">async</span> <span class="title function_">liquidMethodMissing</span>(<span class="params">key</span>) {</span><br><span class="line"> <span class="keyword">const</span> record = <span class="keyword">await</span> db.<span class="title function_">getRecordByKey</span>(key)</span><br><span class="line"> <span class="keyword">return</span> record.<span class="property">value</span></span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="keyword">const</span> context = { <span class="attr">db</span>: <span class="keyword">new</span> <span class="title class_">DBDrop</span>() }</span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(<span class="string">"{{db.coo}}"</span>, context).<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">DBDrop</span> <span class="token keyword">extends</span> <span class="token class-name">Drop</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">async</span> <span class="token function">liquidMethodMissing</span><span class="token punctuation">(</span><span class="token parameter">key</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> record <span class="token operator">=</span> <span class="token keyword">await</span> db<span class="token punctuation">.</span><span class="token function">getRecordByKey</span><span class="token punctuation">(</span>key<span class="token punctuation">)</span>
|
||||
<span class="token keyword">return</span> record<span class="token punctuation">.</span>value
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> context <span class="token operator">=</span> <span class="token punctuation">{</span> <span class="token literal-property property">db</span><span class="token operator">:</span> <span class="token keyword">new</span> <span class="token class-name">DBDrop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">"{{db.coo}}"</span><span class="token punctuation">,</span> context<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="valueOf-NaN" class="article-heading"><a href="#valueOf-NaN" class="headerlink" title="valueOf"></a>valueOf<a class="article-anchor" href="#valueOf-NaN" aria-hidden="true"></a></h2><p>Drops can implement a <code>valueOf()</code> method, the return value of which can be used to replace itself in the output. For example:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">ColorDrop</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Drop</span> {</span><br><span class="line"> <span class="title function_">valueOf</span>(<span class="params"></span>) {</span><br><span class="line"> <span class="keyword">return</span> <span class="string">'red'</span></span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="keyword">const</span> context = { <span class="attr">color</span>: <span class="keyword">new</span> <span class="title class_">ColorDrop</span>() }</span><br><span class="line"><span class="comment">// Outputs: "red"</span></span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(<span class="string">"{{color}}"</span>, context).<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">ColorDrop</span> <span class="token keyword">extends</span> <span class="token class-name">Drop</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">valueOf</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token string">'red'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> context <span class="token operator">=</span> <span class="token punctuation">{</span> <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token keyword">new</span> <span class="token class-name">ColorDrop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span>
|
||||
<span class="token comment">// Outputs: "red"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">"{{color}}"</span><span class="token punctuation">,</span> context<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="toLiquid" class="article-heading"><a href="#toLiquid" class="headerlink" title="toLiquid"></a>toLiquid<a class="article-anchor" href="#toLiquid" aria-hidden="true"></a></h2><p><code>toLiquid()</code> is not a method of <code>Drop</code>, but it can be used to return a <code>Drop</code>. In cases where you have a fixed structure in the <code>context</code> that cannot change its values, you can implement <code>toLiquid()</code> to let LiquidJS use the returned value instead of itself to render the templates.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> context = {</span><br><span class="line"> <span class="attr">person</span>: {</span><br><span class="line"> <span class="attr">firstName</span>: <span class="string">"Jun"</span>,</span><br><span class="line"> <span class="attr">lastName</span>: <span class="string">"Yang"</span>,</span><br><span class="line"> <span class="attr">name</span>: <span class="string">"Jun Yang"</span>,</span><br><span class="line"> <span class="attr">toLiquid</span>: <span class="function">() =></span> ({</span><br><span class="line"> <span class="attr">firstName</span>: <span class="variable language_">this</span>.<span class="property">firstName</span>,</span><br><span class="line"> <span class="attr">lastName</span>: <span class="variable language_">this</span>.<span class="property">lastName</span>,</span><br><span class="line"> <span class="comment">// use a different `name`</span></span><br><span class="line"> <span class="attr">name</span>: <span class="string">"Yang, Jun"</span></span><br><span class="line"> })</span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="comment">// Outputs: "Yang, Jun"</span></span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(<span class="string">"{{person.name}}"</span>, context).<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">const</span> context <span class="token operator">=</span> <span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">person</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">firstName</span><span class="token operator">:</span> <span class="token string">"Jun"</span><span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">lastName</span><span class="token operator">:</span> <span class="token string">"Yang"</span><span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">"Jun Yang"</span><span class="token punctuation">,</span>
|
||||
<span class="token function-variable function">toLiquid</span><span class="token operator">:</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">firstName</span><span class="token operator">:</span> <span class="token keyword">this</span><span class="token punctuation">.</span>firstName<span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">lastName</span><span class="token operator">:</span> <span class="token keyword">this</span><span class="token punctuation">.</span>lastName<span class="token punctuation">,</span>
|
||||
<span class="token comment">// use a different `name`</span>
|
||||
<span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">"Yang, Jun"</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// Outputs: "Yang, Jun"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">"{{person.name}}"</span><span class="token punctuation">,</span> context<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Of course, you can also return a <code>PersonDrop</code> instance in the <code>toLiquid()</code> method and implement this functionality within <code>PersonDrop</code>:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span>, <span class="title class_">Drop</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">class</span> <span class="title class_">PersonDrop</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Drop</span> {</span><br><span class="line"> <span class="title function_">constructor</span>(<span class="params">person</span>) {</span><br><span class="line"> <span class="variable language_">super</span>()</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">person</span> = person</span><br><span class="line"> }</span><br><span class="line"> <span class="title function_">name</span>(<span class="params"></span>) {</span><br><span class="line"> <span class="keyword">return</span> <span class="variable language_">this</span>.<span class="property">person</span>.<span class="property">lastName</span> + <span class="string">", "</span> + <span class="variable language_">this</span>.<span class="property">person</span>.<span class="property">firstName</span></span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> context = {</span><br><span class="line"> <span class="attr">person</span>: {</span><br><span class="line"> <span class="attr">firstName</span>: <span class="string">"Jun"</span>,</span><br><span class="line"> <span class="attr">lastName</span>: <span class="string">"Yang"</span>,</span><br><span class="line"> <span class="attr">name</span>: <span class="string">"Jun Yang"</span>,</span><br><span class="line"> <span class="attr">toLiquid</span>: <span class="keyword">function</span> (<span class="params"></span>) { <span class="keyword">return</span> <span class="keyword">new</span> <span class="title class_">PersonDrop</span>(<span class="variable language_">this</span>) }</span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"><span class="comment">// Outputs: "Yang, Jun"</span></span><br><span class="line">engine.<span class="title function_">parseAndRender</span>(<span class="string">"{{person.name}}"</span>, context).<span class="title function_">then</span>(<span class="function"><span class="params">html</span> =></span> <span class="variable language_">console</span>.<span class="title function_">log</span>(html))</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Drop <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">PersonDrop</span> <span class="token keyword">extends</span> <span class="token class-name">Drop</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">constructor</span><span class="token punctuation">(</span><span class="token parameter">person</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>person <span class="token operator">=</span> person
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token function">name</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span>person<span class="token punctuation">.</span>lastName <span class="token operator">+</span> <span class="token string">", "</span> <span class="token operator">+</span> <span class="token keyword">this</span><span class="token punctuation">.</span>person<span class="token punctuation">.</span>firstName
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> context <span class="token operator">=</span> <span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">person</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">firstName</span><span class="token operator">:</span> <span class="token string">"Jun"</span><span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">lastName</span><span class="token operator">:</span> <span class="token string">"Yang"</span><span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">"Jun Yang"</span><span class="token punctuation">,</span>
|
||||
<span class="token function-variable function">toLiquid</span><span class="token operator">:</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> <span class="token keyword">new</span> <span class="token class-name">PersonDrop</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">)</span> <span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// Outputs: "Yang, Jun"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">"{{person.name}}"</span><span class="token punctuation">,</span> context<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token parameter">html</span> <span class="token operator">=></span> console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>html<span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title"><code>toLiquid()</code> vs. <code>valueOf()</code> Difference</strong><ul>
|
||||
<li><code>valueOf()</code> is typically used to define how the current variable should be rendered, while <code>toLiquid()</code> is often used to convert an object into a Drop or another scope provided to the template.</li>
|
||||
@@ -126,22 +216,28 @@
|
||||
|
||||
<h2 id="Special-Drops" class="article-heading"><a href="#Special-Drops" class="headerlink" title="Special Drops"></a>Special Drops<a class="article-anchor" href="#Special-Drops" aria-hidden="true"></a></h2><p>LiquidJS itself implements several built-in drops to facilitate template writing. This part is compatible with Shopify Liquid, as we need templates to be portable.</p>
|
||||
<h3 id="blank" class="article-heading"><a href="#blank" class="headerlink" title="blank"></a>blank<a class="article-anchor" href="#blank" aria-hidden="true"></a></h3><p>Useful to check whether a string variable is <code>false</code>, <code>null</code>, <code>undefined</code>, an empty string, or a string containing only blank characters.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{% unless author == blank %}</span><br><span class="line"> {{author}}</span><br><span class="line">{% endif %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">unless</span> author <span class="token operator">==</span> blank <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span>author<span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endif</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h3 id="empty" class="article-heading"><a href="#empty" class="headerlink" title="empty"></a>empty<a class="article-anchor" href="#empty" aria-hidden="true"></a></h3><p>Useful to check if an array, string, or object is empty.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{% if authors == empty %}</span><br><span class="line"> Author list is empty</span><br><span class="line">{% endif %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">if</span> authors <span class="token operator">==</span> <span class="token empty keyword">empty</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
Author list is empty
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endif</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title"><code>empty</code> implementation</strong><p>For arrays and strings, LiquidJS checks their <code>.length</code> property. For objects, LiquidJS calls <code>Object.keys()</code> to check whether they have keys.</p>
|
||||
</blockquote>
|
||||
|
||||
<h3 id="nil" class="article-heading"><a href="#nil" class="headerlink" title="nil"></a>nil<a class="article-anchor" href="#nil" aria-hidden="true"></a></h3><p><code>nil</code> Drop is used to check whether a variable is not defined or defined as <code>null</code> or <code>undefined</code>, essentially equivalent to JavaScript <code>== null</code> check.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{% if nonexistent == nil %}</span><br><span class="line"> null variable</span><br><span class="line">{% endif %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">if</span> nonexistent <span class="token operator">==</span> <span class="token boolean">nil</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
null variable
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endif</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h3 id="Other-Drops" class="article-heading"><a href="#Other-Drops" class="headerlink" title="Other Drops"></a>Other Drops<a class="article-anchor" href="#Other-Drops" aria-hidden="true"></a></h3><p>There are still several Drops for specific tags, like <code>forloop</code>, <code>tablerowloop</code>, <code>block</code>, which are covered by respective tag documents.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="render-tag-content.html" class="article-footer-prev" title="Render Tag Content"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="sync-and-async.html" class="article-footer-next" title="Sync and Async"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+15
-9
@@ -99,37 +99,43 @@
|
||||
</ol>
|
||||
<h2 id="HTML-Escape" class="article-heading"><a href="#HTML-Escape" class="headerlink" title="HTML Escape"></a>HTML Escape<a class="article-anchor" href="#HTML-Escape" aria-hidden="true"></a></h2><p>By default output is not escaped. While you can use <a href="../filters/escape.html">escape</a> filter for this:</p>
|
||||
<p>Input</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{{ "1 < 2" | escape }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"1 < 2"</span> <span class="token operator">|</span> <span class="token function filter">escape</span> <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Output</p>
|
||||
<figure class="highlight text"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">1 &lt; 2</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-text" data-language="text"><code class="language-text">1 &lt; 2<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>There’s also <a href="../filters/escape.html">escape_once</a>, <a href="../filters/newline_to_br.html">newline_to_br</a>, <a href="../filters/strip_html.html">strip_html</a> filters for you to fine tune your output.</p>
|
||||
<p>In cases where variables are mostly not trusted, <a href="./options.html#outputEscape">outputEscape</a> can be set to <code>"escape"</code> to apply escape by default. In this case, when you need some output not to be escaped, <a href="../filters/raw.html">raw</a> filter can be used:</p>
|
||||
<p>Input</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">{{ "1 < 2" }}</span><br><span class="line">{{ "<button>OK</button>" | raw }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"1 < 2"</span> <span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"<button>OK</button>"</span> <span class="token operator">|</span> <span class="token keyword">raw</span> <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Output</p>
|
||||
<figure class="highlight text"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">1 &lt; 2</span><br><span class="line"><button>OK</button></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-text" data-language="text"><code class="language-text">1 &lt; 2
|
||||
<button>OK</button><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Liquid-Escape" class="article-heading"><a href="#Liquid-Escape" class="headerlink" title="Liquid Escape"></a>Liquid Escape<a class="article-anchor" href="#Liquid-Escape" aria-hidden="true"></a></h2><p>To disable Liquid language and output strings like <code>{{</code> and <code>{%</code>, the <a href="../filters/raw.html">raw</a> tag can be used.</p>
|
||||
<p>Input</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">{% raw %}</span><br><span class="line"> In LiquidJS, {{ this | escape }} will be HTML-escaped, but</span><br><span class="line"> {{{ that }}} will not.</span><br><span class="line">{% endraw %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">raw</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
In LiquidJS, {{ this | escape }} will be HTML-escaped, but
|
||||
{{{ that }}} will not.
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endraw</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Output</p>
|
||||
<figure class="highlight text"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">In LiquidJS, {{ this | escape }} will be HTML-escaped, but</span><br><span class="line">{{{ that }}} will not.</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-text" data-language="text"><code class="language-text">In LiquidJS, {{ this | escape }} will be HTML-escaped, but
|
||||
{{{ that }}} will not.<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Within strings literals in LiquidJS template, <code>\</code> can be used to escape special characters in string syntax. For example:</p>
|
||||
<p>Input</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{{ "\"" }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"\"</span>" <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Output</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">"</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid">"<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="caching.html" class="article-footer-prev" title="Caching"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="register-filters-tags.html" class="article-footer-next" title="Register Filters/Tags"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -102,26 +102,30 @@
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Outputs" class="article-heading"><a href="#Outputs" class="headerlink" title="Outputs"></a>Outputs<a class="article-anchor" href="#Outputs" aria-hidden="true"></a></h2><p><strong>Outputs</strong> are used to output variables, which can be transformed by filters, into HTML. The following template will insert the value of <code>username</code> into the input’s value:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><input type="text" name="user" value="{{username}}"></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>text<span class="token punctuation">"</span></span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>user<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span>username<span class="token delimiter punctuation">}}</span></span><span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Values in output can be transformed by <strong>filter</strong>s before output. To append a string after the variable:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{{ username | append: ", welcome to LiquidJS!" }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> username <span class="token operator">|</span> <span class="token function filter">append</span><span class="token operator">:</span> <span class="token string">", welcome to LiquidJS!"</span> <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Filters can be chained:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{{ username | append: ", welcome to LiquidJS!" | capitalize }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> username <span class="token operator">|</span> <span class="token function filter">append</span><span class="token operator">:</span> <span class="token string">", welcome to LiquidJS!"</span> <span class="token operator">|</span> <span class="token function filter">capitalize</span> <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>A complete list of filters supported by LiquidJS can be found <a href="../filters/overview.html">here</a>.</p>
|
||||
<h2 id="Tags" class="article-heading"><a href="#Tags" class="headerlink" title="Tags"></a>Tags<a class="article-anchor" href="#Tags" aria-hidden="true"></a></h2><p><strong>Tags</strong> are used to control the template rendering process, manipulating template variables, inter-op with other templates, etc. For example <code>assign</code> can be used to define a variable which can be later used in the template:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{% assign foo = "FOO" %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">assign</span> foo <span class="token operator">=</span> <span class="token string">"FOO"</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Typically tags appear in pairs with a start tag and a corresponding end tag. For example:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">{% if foo == "FOO" %}</span><br><span class="line"> Variable `foo` equals "FOO"</span><br><span class="line">{% else %}</span><br><span class="line"> Variable `foo` not equals "FOO"</span><br><span class="line">{% endif %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">if</span> foo <span class="token operator">==</span> <span class="token string">"FOO"</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
Variable `foo` equals "FOO"
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">else</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
Variable `foo` not equals "FOO"
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">endif</span> <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>A complete list of tags supported by LiquidJS can be found <a href="../tags/overview.html">here</a>.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="setup.html" class="article-footer-next" title="Setup"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -116,7 +116,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="dos.html" class="article-footer-prev" title="DoS"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="changelog.html" class="article-footer-next" title="Changelog"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -106,7 +106,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="plugins.html" class="article-footer-prev" title="Plugins"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="truthy-and-falsy.html" class="article-footer-next" title="Truthy and Falsy"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+18
-7
@@ -93,7 +93,10 @@
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>The <a href="/api/classes/Liquid.html">Liquid</a> constructor accepts a plain object as options to define the behavior of LiquidJS. All of these options are optional thus we can specify any of them, for example the <code>cache</code> option:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>)</span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">cache</span>: <span class="literal">true</span></span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">cache</span><span class="token operator">:</span> <span class="token boolean">true</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">API Document</strong><p>Following is an overview for all the options, for exact types and signatures please refer to <a href="https://liquidjs.com/api/interfaces/LiquidOptions.html" target="_self">LiquidOptions | API</a>.</p>
|
||||
</blockquote>
|
||||
@@ -109,10 +112,10 @@
|
||||
<p>Note: for historical reasons, it’s named dynamicPartials but it also works for layouts.</p>
|
||||
</blockquote>
|
||||
<p><strong>dynamicPartials</strong> indicates whether or not to treat filename arguments in <a href="../tags/include.html">include</a>, <a href="../tags/render.html">render</a>, <a href="../tags/layout.html">layout</a> tags as a variable. Defaults to <code>true</code>. For example, render the following snippet with scope <code>{ file: 'foo.html' }</code> will include the <code>foo.html</code>:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{% include file %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">include</span> file <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Setting <code>dynamicPartials: false</code>, LiquidJS will try to include the file named <code>file</code>, which is weird but allows simpler syntax if your template relations are static:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{% liquid foo.html %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">liquid</span> foo<span class="token punctuation">.</span>html <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note warn"><strong class="note-title">Common Pitfall</strong><p>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" rel="external nofollow noreferrer" 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" rel="external nofollow noreferrer" target="_blank">Quoted Include Paths</a>) which I believe is trying to be compatible with Jekyll.</p>
|
||||
</blockquote>
|
||||
@@ -126,10 +129,18 @@
|
||||
<li>Parameters are under <code>include</code> variable instead of current scope.</li>
|
||||
</ul>
|
||||
<p>For example in the following template, <code>name.html</code> is not quoted, <code>header</code> and <code>"HEADER"</code> are separated by <code>=</code>, and the <code>header</code> parameter is referenced by <code>include.header</code>. More details please check out <a href="../tags/include.html">include</a>.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">// entry template</span><br><span class="line">{% include article.html header="HEADER" content="CONTENT" %}</span><br><span class="line"></span><br><span class="line">// article.html</span><br><span class="line"><article></span><br><span class="line"> <header>{{include.header}}</header></span><br><span class="line"> {{include.content}}</span><br><span class="line"></article></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid">// entry template
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">include</span> <span class="token object">article</span><span class="token punctuation">.</span>html header<span class="token operator">=</span><span class="token string">"HEADER"</span> content<span class="token operator">=</span><span class="token string">"CONTENT"</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
|
||||
// article.html
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>article</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>header</span><span class="token punctuation">></span></span><span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span><span class="token keyword">include</span><span class="token punctuation">.</span>header<span class="token delimiter punctuation">}}</span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>header</span><span class="token punctuation">></span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span><span class="token keyword">include</span><span class="token punctuation">.</span>content<span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>article</span><span class="token punctuation">></span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="extname" class="article-heading"><a href="#extname" class="headerlink" title="extname"></a>extname<a class="article-anchor" href="#extname" aria-hidden="true"></a></h2><p><strong>extname</strong> defines the default extension name to be appended into filenames if the filename has no extension name. Defaults to <code>''</code> which means it’s disabled by default. By setting it to <code>.liquid</code>:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">{% render "foo" %} there's no extname, adds `.liquid` and loads foo.liquid</span><br><span class="line">{% render "foo.html" %} there is an extname already, loads foo.html directly</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">render</span> <span class="token string">"foo"</span> <span class="token delimiter punctuation">%}</span></span> there's no extname, adds `.liquid` and loads foo.liquid
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">render</span> <span class="token string">"foo.html"</span> <span class="token delimiter punctuation">%}</span></span> there is an extname already, loads foo.html directly<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">Legacy Versions</strong><p>Before 2.0.1, <code>extname</code> is set to <code>.liquid</code> by default. To change that you need to set <code>extname: ''</code> explicitly. See <a href="https://github.com/harttle/liquidjs/issues/41" rel="external nofollow noreferrer" target="_blank">#41</a> for details.</p>
|
||||
</blockquote>
|
||||
@@ -149,7 +160,7 @@
|
||||
<p><strong>dateFormat</strong> is used to specify a default format to output dates. <code>%A, %B %-e, %Y at %-l:%M %P %z</code> will be used if not specified. For example, set <code>dateFormat: %Y-%m-%dT%H:%M:%S:%LZ</code> to output all dates in [JavaScript Date.toJson()][<a target="_blank" rel="noopener external nofollow noreferrer" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON]">https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON]</a> format.</p>
|
||||
<h2 id="Trimming" class="article-heading"><a href="#Trimming" class="headerlink" title="Trimming"></a>Trimming<a class="article-anchor" href="#Trimming" aria-hidden="true"></a></h2><p><strong>greedy</strong>, <strong>trimOutputLeft</strong>, <strong>trimOutputRight</strong>, <strong>trimTagLeft</strong>, <strong>trimTagRight</strong> options are used to eliminate extra newlines and indents in templates around Liquid Constructs. See <a href="./whitespace-control.html">Whitespace Control</a> for details.</p>
|
||||
<h2 id="Delimiter" class="article-heading"><a href="#Delimiter" class="headerlink" title="Delimiter"></a>Delimiter<a class="article-anchor" href="#Delimiter" aria-hidden="true"></a></h2><p><strong>outputDelimiterLeft</strong>, <strong>outputDelimiterRight</strong>, <strong>tagDelimiterLeft</strong>, <strong>tagDelimiterRight</strong> are used to customize the delimiters for LiquidJS <a href="./intro-to-liquid.html">Tags and Filters</a>. For example with <code>outputDelimiterLeft: <%=, outputDelimiterRight: %></code> we are able to avoid conflicts with other languages:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><%= username | append: ", welcome to LiquidJS!" %></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-ejs" data-language="ejs"><code class="language-ejs"><span class="token ejs language-ejs"><span class="token delimiter punctuation"><%=</span><span class="token language-javascript"> username <span class="token operator">|</span> append<span class="token operator">:</span> <span class="token string">", welcome to LiquidJS!"</span> </span><span class="token delimiter punctuation">%></span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Strict" class="article-heading"><a href="#Strict" class="headerlink" title="Strict"></a>Strict<a class="article-anchor" href="#Strict" aria-hidden="true"></a></h2><p><strong>strictFilters</strong> is used to assert filter existence. If set to <code>false</code>, undefined filters will be skipped. Otherwise, undefined filters will cause a parse exception. Defaults to <code>false</code>.</p>
|
||||
<p><strong>strictVariables</strong> is used to assert variable existence. If set to <code>false</code>, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause a render exception. Defaults to <code>false</code>.</p>
|
||||
@@ -162,7 +173,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="setup.html" class="article-footer-prev" title="Setup"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="render-file.html" class="article-footer-next" title="Render Files"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -93,31 +93,75 @@
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<h2 id="Access-Raw-Parameters" class="article-heading"><a href="#Access-Raw-Parameters" class="headerlink" title="Access Raw Parameters"></a>Access Raw Parameters<a class="article-anchor" href="#Access-Raw-Parameters" aria-hidden="true"></a></h2><p>As covered in <a href="/tutorials/register-filters-tags.html">Register Filters/Tags</a>, tag parameters is available on <code>tagToken.args</code> as a raw string. For example:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {% random foo bar coo %}</span></span><br><span class="line"><span class="comment">// Output: "foo", "bar" or "coo"</span></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'random'</span>, {</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) {</span><br><span class="line"> <span class="comment">// tagToken.args === "foo bar coo"</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span> = tagToken.<span class="property">args</span>.<span class="title function_">split</span>(<span class="string">' '</span>)</span><br><span class="line"> },</span><br><span class="line"> <span class="title function_">render</span>(<span class="params">context, emitter</span>) {</span><br><span class="line"> <span class="comment">// get a random index</span></span><br><span class="line"> <span class="keyword">const</span> index = <span class="title class_">Math</span>.<span class="title function_">floor</span>(<span class="variable language_">this</span>.<span class="property">items</span>.<span class="property">length</span> * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> <span class="comment">// output that item</span></span><br><span class="line"> emitter.<span class="title function_">write</span>(<span class="variable language_">this</span>.<span class="property">items</span>[index])</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: {% random foo bar coo %}</span>
|
||||
<span class="token comment">// Output: "foo", "bar" or "coo"</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// tagToken.args === "foo bar coo"</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>items <span class="token operator">=</span> tagToken<span class="token punctuation">.</span>args<span class="token punctuation">.</span><span class="token function">split</span><span class="token punctuation">(</span><span class="token string">' '</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// get a random index</span>
|
||||
<span class="token keyword">const</span> index <span class="token operator">=</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// output that item</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">[</span>index<span class="token punctuation">]</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Here’s a JSFiddle version: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/ctj364up/2/">https://jsfiddle.net/ctj364up/2/</a></p>
|
||||
<h2 id="Parse-Parameters-as-Values" class="article-heading"><a href="#Parse-Parameters-as-Values" class="headerlink" title="Parse Parameters as Values"></a>Parse Parameters as Values<a class="article-anchor" href="#Parse-Parameters-as-Values" aria-hidden="true"></a></h2><p>Sometimes we need more dynamic tags and want to pass values to the custom tag instead of static strings. Variables in LiquidJS can be literal (string, number, etc.) or a variable from current context scope.</p>
|
||||
<p>The following modified template also contains 3 values to random from, but they’re values instead of static strings. The first one is string literal, second one is an identifier, third one is a property access sequence containing two identifiers.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{% random "foo" bar obj.coo %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> random <span class="token string">"foo"</span> bar obj<span class="token punctuation">.</span>coo <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>It can be tricky to parse all these cases manually, but there’s a <a href="/api/classes/Tokenizer.html">Tokenizer</a> class in LiquidJS you can make use of.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> { <span class="title class_">Liquid</span>, <span class="title class_">Tokenizer</span>, evalToken } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>)</span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'random'</span>, {</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) {</span><br><span class="line"> <span class="keyword">const</span> tokenizer = <span class="keyword">new</span> <span class="title class_">Tokenizer</span>(tagToken.<span class="property">args</span>)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span> = []</span><br><span class="line"> <span class="keyword">while</span> (!tokenizer.<span class="title function_">end</span>()) {</span><br><span class="line"> <span class="comment">// here readValue() returns a LiteralToken or PropertyAccessToken</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">items</span>.<span class="title function_">push</span>(tokenizer.<span class="title function_">readValue</span>())</span><br><span class="line"> }</span><br><span class="line"> },</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> index = <span class="title class_">Math</span>.<span class="title function_">floor</span>(<span class="variable language_">this</span>.<span class="property">items</span>.<span class="property">length</span> * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> <span class="keyword">const</span> token = <span class="variable language_">this</span>.<span class="property">items</span>[index]</span><br><span class="line"> <span class="comment">// in LiquidJS, we use yield to wait for async call</span></span><br><span class="line"> <span class="keyword">const</span> value = <span class="keyword">yield</span> <span class="title function_">evalToken</span>(token, context)</span><br><span class="line"> emitter.<span class="title function_">write</span>(value)</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Tokenizer<span class="token punctuation">,</span> evalToken <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> tokenizer <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Tokenizer</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>items <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
|
||||
<span class="token keyword">while</span> <span class="token punctuation">(</span><span class="token operator">!</span>tokenizer<span class="token punctuation">.</span><span class="token function">end</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// here readValue() returns a LiteralToken or PropertyAccessToken</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span>tokenizer<span class="token punctuation">.</span><span class="token function">readValue</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> index <span class="token operator">=</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">.</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> token <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>items<span class="token punctuation">[</span>index<span class="token punctuation">]</span>
|
||||
<span class="token comment">// in LiquidJS, we use yield to wait for async call</span>
|
||||
<span class="token keyword">const</span> value <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token function">evalToken</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> context<span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Calling this tag in scope <code>{ bar: "bar", obj: { coo: "coo" } }</code> yields exactly the same result as the first example. See this JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/ctj364up/3/">https://jsfiddle.net/ctj364up/3/</a></p>
|
||||
<blockquote class="note info"><strong class="note-title">Async and Promises</strong><p>Async calls in LiquidJS are implemented by generators directly, for we can call generators in synchronous manner so this tag implementation is also valid for <code>renderSync()</code>, <code>parseAndRenderSync()</code>, <code>renderFileSync()</code>. If you need to await a promise in tag implementation, simply replace <code>await somePromise</code> with <code>yield somePromise</code> and keep <code>* render()</code> instead of <code>async render()</code> will do the trick. See <a href="/tutorials/sync-and-async.html">Sync and Async</a> for more details.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Parse-Key-Value-Pairs-as-Named-Parameters" class="article-heading"><a href="#Parse-Key-Value-Pairs-as-Named-Parameters" class="headerlink" title="Parse Key-Value Pairs as Named Parameters"></a>Parse Key-Value Pairs as Named Parameters<a class="article-anchor" href="#Parse-Key-Value-Pairs-as-Named-Parameters" aria-hidden="true"></a></h2><p>Named parameters become very handy when there’re optional parameters or lots of parameters, in which case the order of parameters is not important. This is exactly what <a href="/api/classes/Hash.html">Hash</a> class is invented for.</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">{% random from:2, to:max %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> random from<span class="token operator">:</span><span class="token number">2</span><span class="token punctuation">,</span> to<span class="token operator">:</span>max <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>In the above example, we’re trying to generate a random number in the range [2, max]. We’ll use <code>Hash</code> to parse <code>from</code> and <code>to</code> parameters.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> { <span class="title class_">Liquid</span>, <span class="title class_">Hash</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>)</span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'random'</span>, {</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken</span>) {</span><br><span class="line"> <span class="comment">// parse the parameters structure into `this.args`</span></span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">args</span> = <span class="keyword">new</span> <span class="title class_">Hash</span>(tagToken.<span class="property">args</span>)</span><br><span class="line"> },</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) {</span><br><span class="line"> <span class="comment">// evaluate the parameters in `context`</span></span><br><span class="line"> <span class="keyword">const</span> {<span class="keyword">from</span>, to} = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">args</span>.<span class="title function_">render</span>(context)</span><br><span class="line"> <span class="keyword">const</span> length = to - <span class="keyword">from</span> + <span class="number">1</span></span><br><span class="line"> <span class="keyword">const</span> value = <span class="keyword">from</span> + <span class="title class_">Math</span>.<span class="title function_">floor</span>(length * <span class="title class_">Math</span>.<span class="title function_">random</span>())</span><br><span class="line"> emitter.<span class="title function_">write</span>(value)</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> <span class="token punctuation">{</span> Liquid<span class="token punctuation">,</span> Hash <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'random'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// parse the parameters structure into `this.args`</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>args <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Hash</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// evaluate the parameters in `context`</span>
|
||||
<span class="token keyword">const</span> <span class="token punctuation">{</span>from<span class="token punctuation">,</span> to<span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>args<span class="token punctuation">.</span><span class="token function">render</span><span class="token punctuation">(</span>context<span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> length <span class="token operator">=</span> to <span class="token operator">-</span> from <span class="token operator">+</span> <span class="token number">1</span>
|
||||
<span class="token keyword">const</span> value <span class="token operator">=</span> from <span class="token operator">+</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span>length <span class="token operator">*</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Rendering <code>{% random from:2, to:max %}</code> in scope <code>{ max: 10 }</code> will generate a random number in the range [2, 10]. See this JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/ctj364up/4/">https://jsfiddle.net/ctj364up/4/</a></p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="access-scope-in-filters.html" class="article-footer-prev" title="Access Scope in Filters"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="render-tag-content.html" class="article-footer-next" title="Render Tag Content"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -93,26 +93,44 @@
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<h2 id="Render-Partials" class="article-heading"><a href="#Render-Partials" class="headerlink" title="Render Partials"></a>Render Partials<a class="article-anchor" href="#Render-Partials" aria-hidden="true"></a></h2><p>For the following template files:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">// file: color.liquid</span><br><span class="line">color: '{{ color }}' shape: '{{ shape }}'</span><br><span class="line"></span><br><span class="line">// file: theme.liquid</span><br><span class="line">{% assign shape = 'circle' %}</span><br><span class="line">{% render 'color.liquid' %}</span><br><span class="line">{% render 'color.liquid' with 'red' %}</span><br><span class="line">{% render 'color.liquid', color: 'yellow', shape: 'square' %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">// file: color.liquid
|
||||
color: '{{ color }}' shape: '{{ shape }}'
|
||||
|
||||
// file: theme.liquid
|
||||
{% assign shape = 'circle' %}
|
||||
{% render 'color.liquid' %}
|
||||
{% render 'color.liquid' with 'red' %}
|
||||
{% render 'color.liquid', color: 'yellow', shape: 'square' %}<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>The output will be:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">color: '' shape: 'circle'</span><br><span class="line">color: 'red' shape: 'circle'</span><br><span class="line">color: 'yellow' shape: 'square'</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">color: '' shape: 'circle'
|
||||
color: 'red' shape: 'circle'
|
||||
color: 'yellow' shape: 'square'<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>More details please refer to the <a href="../tags/render.html">render</a> tag.</p>
|
||||
<blockquote class="note tip"><strong class="note-title">The ".liquid" Extension</strong><p>The “.liquid” extension in <code>layout</code>, <code>render</code> and <code>include</code> can be omitted if Liquid instance is created using <code>extname: ".liquid"</code> option. See <a href="./options.html#extname">the extname option</a> for details.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Layout-Templates-Extends" class="article-heading"><a href="#Layout-Templates-Extends" class="headerlink" title="Layout Templates (Extends)"></a>Layout Templates (Extends)<a class="article-anchor" href="#Layout-Templates-Extends" aria-hidden="true"></a></h2><p>For the following template files:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">// file: default-layout.liquid</span><br><span class="line">Header</span><br><span class="line">{% block content %}My default content{% endblock %}</span><br><span class="line">Footer</span><br><span class="line"></span><br><span class="line">// file: page.liquid</span><br><span class="line">{% layout "default-layout.liquid" %}</span><br><span class="line">{% block content %}My page content{% endblock %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">// file: default-layout.liquid
|
||||
Header
|
||||
{% block content %}My default content{% endblock %}
|
||||
Footer
|
||||
|
||||
// file: page.liquid
|
||||
{% layout "default-layout.liquid" %}
|
||||
{% block content %}My page content{% endblock %}<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>The output of <code>page.liquid</code>:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">Header</span><br><span class="line">My page content</span><br><span class="line">Footer</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">Header
|
||||
My page content
|
||||
Footer<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>More details please refer to the <a href="../tags/layout.html">layout</a> tag.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="render-file.html" class="article-footer-prev" title="Render Files"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="use-in-expressjs.html" class="article-footer-next" title="Use in Express.js"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+15
-3
@@ -95,10 +95,22 @@
|
||||
<p>A number of tags and filters can be encapsulated into a <strong>plugin</strong>, which will be typically installed via npm. This article provides information about how to create and use a plugin.</p>
|
||||
<h2 id="Write-a-Plugin" class="article-heading"><a href="#Write-a-Plugin" class="headerlink" title="Write a Plugin"></a>Write a Plugin<a class="article-anchor" href="#Write-a-Plugin" aria-hidden="true"></a></h2><p>A liquidjs plugin is simple function which takes the <a href="/api/classes/Liquid.html">Liquid class</a> as the first parameter and the Liquid instance for <code>this</code>. We can call liquidjs APIs on <code>this</code> to make certain changes, especially <a href="/harttle/liquidjs/wiki/Register-Filters-Tags">register filters and tags</a>.</p>
|
||||
<p>Now we’ll make a plugin to upper case every letter of the input, save the following snippet to <code>upup.js</code>:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"> * Inside the plugin function, `this` refers to the Liquid instance.</span></span><br><span class="line"><span class="comment"> *</span></span><br><span class="line"><span class="comment"> * <span class="doctag">@param</span> Liquid: provides facilities to implement tags and filters.</span></span><br><span class="line"><span class="comment"> */</span></span><br><span class="line"><span class="variable language_">module</span>.<span class="property">exports</span> = <span class="keyword">function</span> (<span class="params">Liquid</span>) {</span><br><span class="line"> <span class="variable language_">this</span>.<span class="title function_">registerFilter</span>(<span class="string">'upup'</span>, <span class="function"><span class="params">x</span> =></span> x.<span class="title function_">toUpperCase</span>());</span><br><span class="line">}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">/**
|
||||
* Inside the plugin function, `this` refers to the Liquid instance.
|
||||
*
|
||||
* @param Liquid: provides facilities to implement tags and filters.
|
||||
*/</span>
|
||||
module<span class="token punctuation">.</span><span class="token function-variable function">exports</span> <span class="token operator">=</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">Liquid</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'upup'</span><span class="token punctuation">,</span> <span class="token parameter">x</span> <span class="token operator">=></span> x<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Use-a-Plugin" class="article-heading"><a href="#Use-a-Plugin" class="headerlink" title="Use a Plugin"></a>Use a Plugin<a class="article-anchor" href="#Use-a-Plugin" aria-hidden="true"></a></h2><p>Simply pass the plugin function into the <code>.plugin()</code> method:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>()</span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">plugin</span>(<span class="built_in">require</span>(<span class="string">'./upup.js'</span>));</span><br><span class="line">engine</span><br><span class="line"> .<span class="title function_">parseAndRender</span>(<span class="string">'{{ "foo" | upup }}'</span>)</span><br><span class="line"> .<span class="title function_">then</span>(<span class="variable language_">console</span>.<span class="property">log</span>) <span class="comment">// outputs "FOO"</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">plugin</span><span class="token punctuation">(</span><span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'./upup.js'</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
engine
|
||||
<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">'{{ "foo" | upup }}'</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span>console<span class="token punctuation">.</span>log<span class="token punctuation">)</span> <span class="token comment">// outputs "FOO"</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Plugin-List" class="article-heading"><a href="#Plugin-List" class="headerlink" title="Plugin List"></a>Plugin List<a class="article-anchor" href="#Plugin-List" aria-hidden="true"></a></h2><p>Since this library excludes certain features that are available on the Shopify platform but not on the <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/Shopify/liquid/">Shopify/liquid</a> repo, see <a href="/tutorials/differences.html">Differences with Shopify/liquid</a>.</p>
|
||||
<p>Here’s a list of plugins that backfill those features. Feel free to add yours, this file is publicly editable.</p>
|
||||
@@ -109,7 +121,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="whitespace-control.html" class="article-footer-prev" title="Whitespace Control"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="operators.html" class="article-footer-next" title="Operators"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -92,27 +92,67 @@
|
||||
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<h2 id="Register-Tags" class="article-heading"><a href="#Register-Tags" class="headerlink" title="Register Tags"></a>Register Tags<a class="article-anchor" href="#Register-Tags" aria-hidden="true"></a></h2><figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {% upper name %}</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">Value</span>, <span class="title class_">TagToken</span>, <span class="title class_">Context</span>, <span class="title class_">Emitter</span>, <span class="title class_">TopLevelToken</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'upper'</span>, {</span><br><span class="line"> <span class="attr">parse</span>: <span class="keyword">function</span>(<span class="params"><span class="attr">tagToken</span>: <span class="title class_">TagToken</span>, <span class="attr">remainTokens</span>: <span class="title class_">TopLevelToken</span>[]</span>) {</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">value</span> = <span class="keyword">new</span> <span class="title class_">Value</span>(token.<span class="property">args</span>, liquid)</span><br><span class="line"> },</span><br><span class="line"> <span class="attr">render</span>: <span class="keyword">function</span>*(<span class="attr">ctx</span>: <span class="title class_">Context</span>) {</span><br><span class="line"> <span class="keyword">const</span> str = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">value</span>.<span class="title function_">value</span>(ctx); <span class="comment">// 'alice'</span></span><br><span class="line"> <span class="keyword">return</span> str.<span class="title function_">toUpperCase</span>() <span class="comment">// 'ALICE'</span></span><br><span class="line"> }</span><br><span class="line">});</span><br></pre></td></tr></table></figure>
|
||||
<h2 id="Register-Tags" class="article-heading"><a href="#Register-Tags" class="headerlink" title="Register Tags"></a>Register Tags<a class="article-anchor" href="#Register-Tags" aria-hidden="true"></a></h2><pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token comment">// Usage: {% upper name %}</span>
|
||||
<span class="token keyword">import</span> <span class="token punctuation">{</span> Value<span class="token punctuation">,</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function-variable function">parse</span><span class="token operator">:</span> <span class="token keyword">function</span><span class="token punctuation">(</span>tagToken<span class="token operator">:</span> TagToken<span class="token punctuation">,</span> remainTokens<span class="token operator">:</span> TopLevelToken<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Value</span><span class="token punctuation">(</span>token<span class="token punctuation">.</span>args<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token function-variable function">render</span><span class="token operator">:</span> <span class="token keyword">function</span><span class="token operator">*</span><span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> str <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>value<span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span>ctx<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 'alice'</span>
|
||||
<span class="token keyword">return</span> str<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment">// 'ALICE'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<ul>
|
||||
<li><code>parse</code>: Read tokens from <code>remainTokens</code> until your end token.</li>
|
||||
<li><code>render</code>: Combine scope data with your parsed tokens into HTML string.</li>
|
||||
</ul>
|
||||
<p>For complex tag implementation, you can also provide a tag class:</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {% upper name:"alice" %}</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">Hash</span>, <span class="title class_">Tag</span>, <span class="title class_">TagToken</span>, <span class="title class_">Context</span>, <span class="title class_">Emitter</span>, <span class="title class_">TopLevelToken</span>, <span class="title class_">Liquid</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'upper'</span>, <span class="keyword">class</span> <span class="title class_">UpperTag</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Tag</span> {</span><br><span class="line"> <span class="keyword">private</span> <span class="attr">hash</span>: <span class="title class_">Hash</span></span><br><span class="line"> <span class="title function_">constructor</span>(<span class="params"><span class="attr">tagToken</span>: <span class="title class_">TagToken</span>, <span class="attr">remainTokens</span>: <span class="title class_">TopLevelToken</span>[], <span class="attr">liquid</span>: <span class="title class_">Liquid</span></span>) {</span><br><span class="line"> <span class="variable language_">super</span>(tagToken, remainTokens, liquid)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">hash</span> = <span class="keyword">new</span> <span class="title class_">Hash</span>(tagToken.<span class="property">args</span>)</span><br><span class="line"> }</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params"><span class="attr">ctx</span>: <span class="title class_">Context</span></span>) {</span><br><span class="line"> <span class="keyword">const</span> hash = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">hash</span>.<span class="title function_">render</span>();</span><br><span class="line"> <span class="keyword">return</span> hash.<span class="property">name</span>.<span class="title function_">toUpperCase</span>() <span class="comment">// 'ALICE'</span></span><br><span class="line"> }</span><br><span class="line">});</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token comment">// Usage: {% upper name:"alice" %}</span>
|
||||
<span class="token keyword">import</span> <span class="token punctuation">{</span> Hash<span class="token punctuation">,</span> Tag<span class="token punctuation">,</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken<span class="token punctuation">,</span> Liquid <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token keyword">class</span> <span class="token class-name">UpperTag</span> <span class="token keyword">extends</span> <span class="token class-name">Tag</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">private</span> hash<span class="token operator">:</span> Hash
|
||||
<span class="token function">constructor</span><span class="token punctuation">(</span>tagToken<span class="token operator">:</span> TagToken<span class="token punctuation">,</span> remainTokens<span class="token operator">:</span> TopLevelToken<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span> liquid<span class="token operator">:</span> Liquid<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">,</span> remainTokens<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>hash <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Hash</span><span class="token punctuation">(</span>tagToken<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> hash <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>hash<span class="token punctuation">.</span><span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">return</span> hash<span class="token punctuation">.</span>name<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment">// 'ALICE'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>See existing tag implementations here: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/tree/master/src/tags">https://github.com/harttle/liquidjs/tree/master/src/tags</a><br>See demo example here: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/demo/typescript/index.ts">https://github.com/harttle/liquidjs/blob/master/demo/typescript/index.ts</a></p>
|
||||
<h2 id="Register-Filters" class="article-heading"><a href="#Register-Filters" class="headerlink" title="Register Filters"></a>Register Filters<a class="article-anchor" href="#Register-Filters" aria-hidden="true"></a></h2><figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {{ name | upper }}</span></span><br><span class="line">engine.<span class="title function_">registerFilter</span>(<span class="string">'upper'</span>, <span class="function"><span class="params">v</span> =></span> v.<span class="title function_">toUpperCase</span>())</span><br></pre></td></tr></table></figure>
|
||||
<h2 id="Register-Filters" class="article-heading"><a href="#Register-Filters" class="headerlink" title="Register Filters"></a>Register Filters<a class="article-anchor" href="#Register-Filters" aria-hidden="true"></a></h2><pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: {{ name | upper }}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token parameter">v</span> <span class="token operator">=></span> v<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Filter arguments will be passed to the registered filter function, for example:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// Usage: {{ 1 | add: 2, 3 }}</span></span><br><span class="line">engine.<span class="title function_">registerFilter</span>(<span class="string">'add'</span>, <span class="function">(<span class="params">initial, arg1, arg2</span>) =></span> initial + arg1 + arg2)</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// Usage: {{ 1 | add: 2, 3 }}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'add'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">initial<span class="token punctuation">,</span> arg1<span class="token punctuation">,</span> arg2</span><span class="token punctuation">)</span> <span class="token operator">=></span> initial <span class="token operator">+</span> arg1 <span class="token operator">+</span> arg2<span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>See existing filter implementations here: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/tree/master/src/filters">https://github.com/harttle/liquidjs/tree/master/src/filters</a></p>
|
||||
<h2 id="Unregister-Tags-Filters" class="article-heading"><a href="#Unregister-Tags-Filters" class="headerlink" title="Unregister Tags/Filters"></a>Unregister Tags/Filters<a class="article-anchor" href="#Unregister-Tags-Filters" aria-hidden="true"></a></h2><p>In some cases it’s desirable to disable some tags/filters (see <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/issues/324">#324</a>), you’ll need to register a dummy tag/filter in which an corresponding Error throws.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// disable a tag</span></span><br><span class="line"><span class="keyword">const</span> disabledTag = {</span><br><span class="line"> <span class="attr">parse</span>: <span class="keyword">function</span>(<span class="params">token</span>) {</span><br><span class="line"> <span class="keyword">throw</span> <span class="keyword">new</span> <span class="title class_">Error</span>(<span class="string">`tag "<span class="subst">${token.name}</span>" disabled`</span>);</span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'include'</span>, disabledTag);</span><br><span class="line"></span><br><span class="line"><span class="comment">// disable a filter</span></span><br><span class="line"><span class="keyword">function</span> <span class="title function_">disabledFilter</span>(<span class="params">name</span>) {</span><br><span class="line"> <span class="keyword">return</span> <span class="keyword">function</span> (<span class="params"></span>) {</span><br><span class="line"> <span class="keyword">throw</span> <span class="keyword">new</span> <span class="title class_">Error</span>(<span class="string">`filter "<span class="subst">${name}</span>" disabled`</span>);</span><br><span class="line"> }</span><br><span class="line">}</span><br><span class="line">engine.<span class="title function_">registerFilter</span>(<span class="string">'plus'</span>, <span class="title function_">disabledFilter</span>(<span class="string">'plus'</span>));</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token comment">// disable a tag</span>
|
||||
<span class="token keyword">const</span> disabledTag <span class="token operator">=</span> <span class="token punctuation">{</span>
|
||||
<span class="token function-variable function">parse</span><span class="token operator">:</span> <span class="token keyword">function</span><span class="token punctuation">(</span><span class="token parameter">token</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name">Error</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">tag "</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>token<span class="token punctuation">.</span>name<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">" disabled</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'include'</span><span class="token punctuation">,</span> disabledTag<span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">// disable a filter</span>
|
||||
<span class="token keyword">function</span> <span class="token function">disabledFilter</span><span class="token punctuation">(</span><span class="token parameter">name</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name">Error</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">filter "</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>name<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">" disabled</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerFilter</span><span class="token punctuation">(</span><span class="token string">'plus'</span><span class="token punctuation">,</span> <span class="token function">disabledFilter</span><span class="token punctuation">(</span><span class="token string">'plus'</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="escaping.html" class="article-footer-prev" title="Escaping"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="access-scope-in-filters.html" class="article-footer-next" title="Access Scope in Filters"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -94,17 +94,31 @@
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>For a typical project there could be a directory of template files, you’ll need to set the <a href="/api/interfaces/LiquidOptions.html#root">template root</a> and call <a href="/api/classes/Liquid.html#renderFile">renderFile</a> or <a href="/api/classes/Liquid.html#renderFileSync">renderFileSync</a> to render a specific file.</p>
|
||||
<h2 id="Render-a-File" class="article-heading"><a href="#Render-a-File" class="headerlink" title="Render a File"></a>Render a File<a class="article-anchor" href="#Render-a-File" aria-hidden="true"></a></h2><p>For example you have a directory of templates like this:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">.</span><br><span class="line">├── index.js</span><br><span class="line">└── views/</span><br><span class="line"> ├── hello.liquid</span><br><span class="line"> └── world.liquid</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">.
|
||||
├── index.js
|
||||
└── views/
|
||||
├── hello.liquid
|
||||
└── world.liquid<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p><code>hello.liquid</code> contains a single line `name: {{name}}`.<br>Now save the following contents into <code>index.js</code>:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">root</span>: path.<span class="title function_">resolve</span>(__dirname, <span class="string">'views/'</span>), <span class="comment">// root for layouts/includes lookup</span></span><br><span class="line"> <span class="attr">extname</span>: <span class="string">'.liquid'</span> <span class="comment">// used for layouts/includes, defaults ""</span></span><br><span class="line">});</span><br><span class="line">engine</span><br><span class="line"> .<span class="title function_">renderFile</span>(<span class="string">"hello"</span>, {<span class="attr">name</span>: <span class="string">'alice'</span>}) <span class="comment">// will read and render `views/hello.liquid`</span></span><br><span class="line"> .<span class="title function_">then</span>(<span class="variable language_">console</span>.<span class="property">log</span>) <span class="comment">// outputs "Alice"</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">root</span><span class="token operator">:</span> path<span class="token punctuation">.</span><span class="token function">resolve</span><span class="token punctuation">(</span>__dirname<span class="token punctuation">,</span> <span class="token string">'views/'</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token comment">// root for layouts/includes lookup</span>
|
||||
<span class="token literal-property property">extname</span><span class="token operator">:</span> <span class="token string">'.liquid'</span> <span class="token comment">// used for layouts/includes, defaults ""</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
engine
|
||||
<span class="token punctuation">.</span><span class="token function">renderFile</span><span class="token punctuation">(</span><span class="token string">"hello"</span><span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token comment">// will read and render `views/hello.liquid`</span>
|
||||
<span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span>console<span class="token punctuation">.</span>log<span class="token punctuation">)</span> <span class="token comment">// outputs "Alice"</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Run <code>node index.js</code> and you’ll get output like this:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">> node index.js</span><br><span class="line">name: alice</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">> node index.js
|
||||
name: alice<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Template-Lookup" class="article-heading"><a href="#Template-Lookup" class="headerlink" title="Template Lookup"></a>Template Lookup<a class="article-anchor" href="#Template-Lookup" aria-hidden="true"></a></h2><p>Template files names passed to <a href="/api/classes/Liquid.html#renderFile">renderFile</a>, <a href="/api/classes/Liquid.html#parseFile">parseFile</a>, <a href="/api/classes/Liquid.html#renderFileSync">renderFileSync</a>, <a href="/api/classes/Liquid.html#parseFileSync">parseFileSync</a> APIs,<br>and <a target="_blank" rel="noopener external nofollow noreferrer" href="https://help.shopify.com/themes/liquid/tags/theme-tags#include">include</a>, <a target="_blank" rel="noopener external nofollow noreferrer" href="https://help.shopify.com/en/themes/liquid/tags/theme-tags#layout">layout</a> tags are resolved against <a href="/api/interfaces/LiquidOptions.html#root">the root option</a>.</p>
|
||||
<p>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.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">root</span>: [<span class="string">'views/'</span>, <span class="string">'views/partials/'</span>],</span><br><span class="line"> <span class="attr">extname</span>: <span class="string">'.liquid'</span></span><br><span class="line">});</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">[</span><span class="token string">'views/'</span><span class="token punctuation">,</span> <span class="token string">'views/partials/'</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
|
||||
<span class="token literal-property property">extname</span><span class="token operator">:</span> <span class="token string">'.liquid'</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note tip"><strong class="note-title">Relative Paths</strong><p>Relative paths in <code>root</code> will be resolved against <code>cwd()</code>.</p>
|
||||
</blockquote>
|
||||
@@ -122,19 +136,48 @@
|
||||
<p>If fetch fails, a 404/500 error or network failures for example, an <code>ENOENT</code> error will be thrown.<br>Here’s a demo for browsers: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/tree/master/demo/browser">demo/browser</a>.</p>
|
||||
<h2 id="Abstract-File-System" class="article-heading"><a href="#Abstract-File-System" class="headerlink" title="Abstract File System"></a>Abstract File System<a class="article-anchor" href="#Abstract-File-System" aria-hidden="true"></a></h2><p>LiquidJS defines an <a href="/api/interfaces/FS.html">abstract file system interface</a> and the default implementation is <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/fs-impl.ts">src/fs/fs-impl.ts</a> for Node.js and <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/fs-impl-browser.ts">src/build/fs-impl-browser.ts</a> for the browser bundle.</p>
|
||||
<p>The <code>Liquid</code> constructor provides a <a href="/api/interfaces/LiquidOptions.html#fs">fs</a> option to specify the file system implementation. It’s supposed to be used to define customized template fetching logic, i.e. fetch template from a database table, like:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">fs</span>: {</span><br><span class="line"> <span class="title function_">readFileSync</span> (file) {</span><br><span class="line"> <span class="keyword">return</span> db.<span class="title function_">model</span>(<span class="string">'Template'</span>).<span class="title function_">findByIdSync</span>(file).<span class="property">text</span></span><br><span class="line"> },</span><br><span class="line"> <span class="keyword">async</span> <span class="title function_">readFile</span> (file) {</span><br><span class="line"> <span class="keyword">const</span> template = <span class="keyword">await</span> db.<span class="title function_">model</span>(<span class="string">'Template'</span>).<span class="title function_">findById</span>(file)</span><br><span class="line"> <span class="keyword">return</span> template.<span class="property">text</span></span><br><span class="line"> },</span><br><span class="line"> <span class="title function_">existsSync</span> () {</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> },</span><br><span class="line"> <span class="keyword">async</span> <span class="title function_">exists</span> () {</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> },</span><br><span class="line"> <span class="title function_">contains</span> () {</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> },</span><br><span class="line"> <span class="title function_">resolve</span>(<span class="params">root, file, ext</span>) {</span><br><span class="line"> <span class="keyword">return</span> file</span><br><span class="line"> }</span><br><span class="line"> }</span><br><span class="line">});</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">fs</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">readFileSync</span> <span class="token punctuation">(</span><span class="token parameter">file</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> db<span class="token punctuation">.</span><span class="token function">model</span><span class="token punctuation">(</span><span class="token string">'Template'</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">findByIdSync</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span><span class="token punctuation">.</span>text
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token keyword">async</span> <span class="token function">readFile</span> <span class="token punctuation">(</span><span class="token parameter">file</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> template <span class="token operator">=</span> <span class="token keyword">await</span> db<span class="token punctuation">.</span><span class="token function">model</span><span class="token punctuation">(</span><span class="token string">'Template'</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">findById</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span>
|
||||
<span class="token keyword">return</span> template<span class="token punctuation">.</span>text
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token function">existsSync</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token boolean">true</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token keyword">async</span> <span class="token function">exists</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token boolean">true</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token function">contains</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> <span class="token boolean">true</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token function">resolve</span><span class="token punctuation">(</span><span class="token parameter">root<span class="token punctuation">,</span> file<span class="token punctuation">,</span> ext</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">return</span> file
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note warn"><strong class="note-title">Path Traversal Vulnerability</strong><p>The default value of <code>contains()</code> always returns true. That means when specifying an abstract file system, you’ll need to provide a proper <code>contains()</code> to avoid expose such vulnerabilities.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="In-memory-Template" class="article-heading"><a href="#In-memory-Template" class="headerlink" title="In-memory Template"></a>In-memory Template<a class="article-anchor" href="#In-memory-Template" aria-hidden="true"></a></h2><p>To facilitate rendering w/o files, there’s a <code>templates</code> option to specify a mapping of filenames and their content. LiquidJS will read templates from the mapping.</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">templates</span>: {</span><br><span class="line"> <span class="string">'views/entry'</span>: <span class="string">'header {% include "../partials/footer" %}'</span>,</span><br><span class="line"> <span class="string">'partials/footer'</span>: <span class="string">'footer'</span></span><br><span class="line"> }</span><br><span class="line">})</span><br><span class="line">engine.<span class="title function_">renderFileSync</span>(<span class="string">'views/entry'</span>))</span><br><span class="line"><span class="comment">// Result: 'header footer'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
templates<span class="token operator">:</span> <span class="token punctuation">{</span>
|
||||
<span class="token string-property property">'views/entry'</span><span class="token operator">:</span> <span class="token string">'header {% include "../partials/footer" %}'</span><span class="token punctuation">,</span>
|
||||
<span class="token string-property property">'partials/footer'</span><span class="token operator">:</span> <span class="token string">'footer'</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">renderFileSync</span><span class="token punctuation">(</span><span class="token string">'views/entry'</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// Result: 'header footer'</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Note that file system options like <code>root</code>, <code>layouts</code>, <code>partials</code>, <code>relativeReference</code> will be ignored when <code>templates</code> is specified.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="options.html" class="article-footer-prev" title="Options"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="partials-and-layouts.html" class="article-footer-next" title="Includes and Layouts"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -94,10 +94,14 @@
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>Custom tags can have content template and can be nested. This article describes how to implement custom tags that consists of a <em>begin tag</em>, an <em>end tag</em>, and template content between them.</p>
|
||||
<h2 id="Render-Tag-Content" class="article-heading"><a href="#Render-Tag-Content" class="headerlink" title="Render Tag Content"></a>Render Tag Content<a class="article-anchor" href="#Render-Tag-Content" aria-hidden="true"></a></h2><p>We’ll start with a simple tag <code>wrap</code> which wraps its content into a <code><div class="wrapper"></div></code> element:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{% wrap %}</span><br><span class="line"> {{ "hello world!" | capitalize }}</span><br><span class="line">{% endwrap %}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> wrap <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"hello world!"</span> <span class="token operator">|</span> <span class="token function filter">capitalize</span> <span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> endwrap <span class="token delimiter punctuation">%}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Expected output:</p>
|
||||
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag"><<span class="name">div</span> <span class="attr">class</span>=<span class="string">'wrapper'</span>></span></span><br><span class="line"> Hello world!</span><br><span class="line"><span class="tag"></<span class="name">div</span>></span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-markup" data-language="markup"><code class="language-markup"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">'</span>wrapper<span class="token punctuation">'</span></span><span class="token punctuation">></span></span>
|
||||
Hello world!
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Firstly, <a href="./register-filters-tags.html">register</a> a tag with name <code>wrap</code> and parse the content into <code>this.tpls</code>. Here in <code>parse(tagToken, remainTokens)</code>,</p>
|
||||
<ul>
|
||||
@@ -105,25 +109,77 @@
|
||||
<li><code>remainTokens</code> is an array of all tokens following <code>{% wrap %}</code> until the end of this template file.</li>
|
||||
</ul>
|
||||
<p>Basically, what we need to do is take/<code>.shift()</code> enough tags from <code>remainTokens</code> until we got a <code>endwrap</code> token (the name can be arbitrary, but in convention, we need it to be <code>endwrap</code>). And if there’s no <code>endwrap</code> until the end of template file, we need to throw an tag-not-closed <code>Error</code>.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br></pre></td><td class="code"><pre><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'wrap'</span>, {</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken, remainTokens</span>) {</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">tpls</span> = []</span><br><span class="line"> <span class="keyword">let</span> closed = <span class="literal">false</span></span><br><span class="line"> <span class="keyword">while</span>(remainTokens.<span class="property">length</span>) {</span><br><span class="line"> <span class="keyword">let</span> token = remainTokens.<span class="title function_">shift</span>()</span><br><span class="line"> <span class="comment">// we got the end tag! stop taking tokens</span></span><br><span class="line"> <span class="keyword">if</span> (token.<span class="property">name</span> === <span class="string">'endwrap'</span>) {</span><br><span class="line"> closed = <span class="literal">true</span></span><br><span class="line"> <span class="keyword">break</span></span><br><span class="line"> }</span><br><span class="line"> <span class="comment">// parse token into template</span></span><br><span class="line"> <span class="comment">// parseToken() may consume more than 1 tokens</span></span><br><span class="line"> <span class="comment">// e.g. {% if %}...{% endif %}</span></span><br><span class="line"> <span class="keyword">let</span> tpl = <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">parser</span>.<span class="title function_">parseToken</span>(token, remainTokens)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">tpls</span>.<span class="title function_">push</span>(tpl)</span><br><span class="line"> }</span><br><span class="line"> <span class="keyword">if</span> (!closed) <span class="keyword">throw</span> <span class="keyword">new</span> <span class="title class_">Error</span>(<span class="string">`tag <span class="subst">${tagToken.getText()}</span> not closed`</span>)</span><br><span class="line"> },</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) {</span><br><span class="line"> emitter.<span class="title function_">write</span>(<span class="string">"<div class='wrapper'>"</span>)</span><br><span class="line"> <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">renderer</span>.<span class="title function_">renderTemplates</span>(<span class="variable language_">this</span>.<span class="property">tpls</span>, context, emitter)</span><br><span class="line"> emitter.<span class="title function_">write</span>(<span class="string">"</div>"</span>)</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript">engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'wrap'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken<span class="token punctuation">,</span> remainTokens</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>tpls <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
|
||||
<span class="token keyword">let</span> closed <span class="token operator">=</span> <span class="token boolean">false</span>
|
||||
<span class="token keyword">while</span><span class="token punctuation">(</span>remainTokens<span class="token punctuation">.</span>length<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">let</span> token <span class="token operator">=</span> remainTokens<span class="token punctuation">.</span><span class="token function">shift</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// we got the end tag! stop taking tokens</span>
|
||||
<span class="token keyword">if</span> <span class="token punctuation">(</span>token<span class="token punctuation">.</span>name <span class="token operator">===</span> <span class="token string">'endwrap'</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
closed <span class="token operator">=</span> <span class="token boolean">true</span>
|
||||
<span class="token keyword">break</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token comment">// parse token into template</span>
|
||||
<span class="token comment">// parseToken() may consume more than 1 tokens</span>
|
||||
<span class="token comment">// e.g. {% if %}...{% endif %}</span>
|
||||
<span class="token keyword">let</span> tpl <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>parser<span class="token punctuation">.</span><span class="token function">parseToken</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> remainTokens<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span>tpl<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token operator">!</span>closed<span class="token punctuation">)</span> <span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name">Error</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">tag </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tagToken<span class="token punctuation">.</span><span class="token function">getText</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> not closed</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token string">"<div class='wrapper'>"</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>renderer<span class="token punctuation">.</span><span class="token function">renderTemplates</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">,</span> context<span class="token punctuation">,</span> emitter<span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token string">"</div>"</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p><code>.renderTemplates()</code> can be async, we need <code>yield</code> to wait it complete. More details on async in LiquidJS, please refer to <a href="./sync-and-async.html">Sync and Async</a>. Other parts of <code>render()</code> method is quite straightforward. Here’s a JSFiddle version: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/por0zcn1/3/">https://jsfiddle.net/por0zcn1/3/</a></p>
|
||||
<h2 id="Using-ParseStream" class="article-heading"><a href="#Using-ParseStream" class="headerlink" title="Using ParseStream"></a>Using ParseStream<a class="article-anchor" href="#Using-ParseStream" aria-hidden="true"></a></h2><p>When it comes to complex tags like <a href="../tags/for.html">for</a> and <a href="../tags/if.html">if</a>, the <code>parse()</code> can be very complicated. There’s a <a href="/api/classes/ParseStream.html">ParseStream</a> utility to organize the <code>parse()</code> in event-based style. Following is a re-written <code>parse()</code> using <code>ParseStream</code> and does exactly the same as above example.</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">parse</span>(<span class="params">tagToken, remainTokens</span>) {</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">tpls</span> = []</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">parser</span>.<span class="title function_">parseStream</span>(remainTokens)</span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'template'</span>, <span class="function"><span class="params">tpl</span> =></span> <span class="variable language_">this</span>.<span class="property">tpls</span>.<span class="title function_">push</span>(tpl))</span><br><span class="line"> <span class="comment">// note that we cannot use arrow function because we need `this`</span></span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'tag:endwrap'</span>, <span class="keyword">function</span> (<span class="params"></span>) { <span class="variable language_">this</span>.<span class="title function_">stop</span>() })</span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'end'</span>, <span class="function">() =></span> { <span class="keyword">throw</span> <span class="keyword">new</span> <span class="title class_">Error</span>(<span class="string">`tag <span class="subst">${tagToken.getText()}</span> not closed`</span>) })</span><br><span class="line"> .<span class="title function_">start</span>()</span><br><span class="line">}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken<span class="token punctuation">,</span> remainTokens</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>tpls <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>parser<span class="token punctuation">.</span><span class="token function">parseStream</span><span class="token punctuation">(</span>remainTokens<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'template'</span><span class="token punctuation">,</span> <span class="token parameter">tpl</span> <span class="token operator">=></span> <span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span>tpl<span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token comment">// note that we cannot use arrow function because we need `this`</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'tag:endwrap'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">stop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'end'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> <span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name">Error</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">tag </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tagToken<span class="token punctuation">.</span><span class="token function">getText</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> not closed</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">start</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Here’s a JSFiddle version: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/por0zcn1/4/">https://jsfiddle.net/por0zcn1/4/</a>. For simplicity, the following examples are implemented using <code>ParseStream</code>.</p>
|
||||
<h2 id="Manipulate-the-Context" class="article-heading"><a href="#Manipulate-the-Context" class="headerlink" title="Manipulate the Context"></a>Manipulate the Context<a class="article-anchor" href="#Manipulate-the-Context" aria-hidden="true"></a></h2><p>The <code>wrap</code> tag above doesn’t seem to be very useful, without using that tag we can render the content anyway. Now we’re going to implement a <code>repeat</code> tag to render the content 2 times (we can also add a <a href="./parse-parameters.html">parameter</a> to render arbitrary times).</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">{% repeat %}</span><br><span class="line"> {{ repeat.i }}. {{ "hello world!" | capitalize }}</span><br><span class="line">{% endrepeat %}`</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> repeat <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> repeat<span class="token punctuation">.</span>i <span class="token delimiter punctuation">}}</span></span>. <span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> <span class="token string">"hello world!"</span> <span class="token operator">|</span> <span class="token function filter">capitalize</span> <span class="token delimiter punctuation">}}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> endrepeat <span class="token delimiter punctuation">%}</span></span>`<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Expected outputs:</p>
|
||||
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">1. Hello world!</span><br><span class="line">2. Hello world!</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-markup" data-language="markup"><code class="language-markup">1. Hello world!
|
||||
2. Hello world!<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>As you’ve noticed, there’s an additional <code>repeat.i</code> in the context of <code>repeat</code>. That is implemented by manipulating the <em>Context</em>.</p>
|
||||
<blockquote class="note info"><strong class="note-title">Context</strong><p><em>Context</em> defines the value of each variable in Liquid template. In LiquidJS, a <code>Context</code> consists of a stack of <code>Scope</code>s. A <em>Scope</em> is a plain object like the one specified in <code>engine.render(tpl, scope)</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<p>Each time we enter a new <em>Context</em>, we need to push a new <em>Scope</em>. And when we finish rendering and exit the <em>Context</em>, we pop the <em>Scope</em> from the <em>Context</em>. As you can see in the following implementation:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'repeat'</span>, {</span><br><span class="line"> <span class="title function_">parse</span>(<span class="params">tagToken, remainTokens</span>) {</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">tpls</span> = []</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">parser</span>.<span class="title function_">parseStream</span>(remainTokens)</span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'template'</span>, <span class="function"><span class="params">tpl</span> =></span> <span class="variable language_">this</span>.<span class="property">tpls</span>.<span class="title function_">push</span>(tpl))</span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'tag:endrepeat'</span>, <span class="keyword">function</span> (<span class="params"></span>) { <span class="variable language_">this</span>.<span class="title function_">stop</span>() })</span><br><span class="line"> .<span class="title function_">on</span>(<span class="string">'end'</span>, <span class="function">() =></span> { <span class="keyword">throw</span> <span class="keyword">new</span> <span class="title class_">Error</span>(<span class="string">`tag <span class="subst">${tagToken.getText()}</span> not closed`</span>) })</span><br><span class="line"> .<span class="title function_">start</span>()</span><br><span class="line"> },</span><br><span class="line"> * <span class="title function_">render</span>(<span class="params">context, emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> repeat = { <span class="attr">i</span>: <span class="number">1</span> }</span><br><span class="line"> context.<span class="title function_">push</span>({ repeat })</span><br><span class="line"> <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">renderer</span>.<span class="title function_">renderTemplates</span>(<span class="variable language_">this</span>.<span class="property">tpls</span>, context, emitter)</span><br><span class="line"> repeat.<span class="property">i</span>++</span><br><span class="line"> <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">liquid</span>.<span class="property">renderer</span>.<span class="title function_">renderTemplates</span>(<span class="variable language_">this</span>.<span class="property">tpls</span>, context, emitter)</span><br><span class="line"> context.<span class="title function_">pop</span>()</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript">engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'repeat'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">parse</span><span class="token punctuation">(</span><span class="token parameter">tagToken<span class="token punctuation">,</span> remainTokens</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>tpls <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>parser<span class="token punctuation">.</span><span class="token function">parseStream</span><span class="token punctuation">(</span>remainTokens<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'template'</span><span class="token punctuation">,</span> <span class="token parameter">tpl</span> <span class="token operator">=></span> <span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span>tpl<span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'tag:endrepeat'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">stop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'end'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> <span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name">Error</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">tag </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tagToken<span class="token punctuation">.</span><span class="token function">getText</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> not closed</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">start</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span><span class="token punctuation">(</span><span class="token parameter">context<span class="token punctuation">,</span> emitter</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> repeat <span class="token operator">=</span> <span class="token punctuation">{</span> <span class="token literal-property property">i</span><span class="token operator">:</span> <span class="token number">1</span> <span class="token punctuation">}</span>
|
||||
context<span class="token punctuation">.</span><span class="token function">push</span><span class="token punctuation">(</span><span class="token punctuation">{</span> repeat <span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>renderer<span class="token punctuation">.</span><span class="token function">renderTemplates</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">,</span> context<span class="token punctuation">,</span> emitter<span class="token punctuation">)</span>
|
||||
repeat<span class="token punctuation">.</span>i<span class="token operator">++</span>
|
||||
<span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>liquid<span class="token punctuation">.</span>renderer<span class="token punctuation">.</span><span class="token function">renderTemplates</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>tpls<span class="token punctuation">,</span> context<span class="token punctuation">,</span> emitter<span class="token punctuation">)</span>
|
||||
context<span class="token punctuation">.</span><span class="token function">pop</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>The <code>parse()</code> is exactly the same as <code>wrap</code> tag, we repeat the content simply by calling <code>.renderTemplates(this.tpls)</code> twice during <code>render()</code>. Here’s the JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="https://jsfiddle.net/por0zcn1/2/">https://jsfiddle.net/por0zcn1/2/</a></p>
|
||||
<blockquote class="note warn"><strong class="note-title">Use Push & Pop in Pairs</strong><p><code>context.push()</code> and <code>context.pop()</code> have to be used in pairs. Failing to <code>pop()</code> the <em>Scope</em> you pushed will leak the <em>Scope</em> to latter templates and may corrupt the <em>Context</em> stack.</p>
|
||||
@@ -132,7 +188,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="parse-parameters.html" class="article-footer-prev" title="Parse Parameters"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="drops.html" class="article-footer-next" title="Liquid Drops"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
+26
-11
@@ -94,21 +94,34 @@
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>In case you’re not familiar with Liquid Template Language, see <a href="./intro-to-liquid.html">Introduction to Liquid Template Language</a>.</p>
|
||||
<h2 id="LiquidJS-in-Node-js" class="article-heading"><a href="#LiquidJS-in-Node-js" class="headerlink" title="LiquidJS in Node.js"></a>LiquidJS in Node.js<a class="article-anchor" href="#LiquidJS-in-Node-js" aria-hidden="true"></a></h2><p>Install via npm:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npm install --save liquidjs</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash"><span class="token function">npm</span> <span class="token function">install</span> <span class="token parameter variable">--save</span> liquidjs<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>);</span><br><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>();</span><br><span class="line"></span><br><span class="line">engine</span><br><span class="line"> .<span class="title function_">parseAndRender</span>(<span class="string">'{{name | capitalize}}'</span>, {<span class="attr">name</span>: <span class="string">'alice'</span>})</span><br><span class="line"> .<span class="title function_">then</span>(<span class="variable language_">console</span>.<span class="property">log</span>); <span class="comment">// outputs 'Alice'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
engine
|
||||
<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">'{{name | capitalize}}'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span><span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span>console<span class="token punctuation">.</span>log<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// outputs 'Alice'</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">Working Demo</strong><p>Here’s a working demo for LiquidJS usage in Node.js: <a href="https://github.com/harttle/liquidjs/blob/master/demo/nodejs/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/nodejs/</a>.</p>
|
||||
</blockquote>
|
||||
|
||||
<p>Type definitions for LiquidJS are also exported and published, which makes it more enjoyable for TypeScript projects:</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">Liquid</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span>;</span><br><span class="line"><span class="keyword">const</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>();</span><br><span class="line"></span><br><span class="line">engine</span><br><span class="line"> .<span class="title function_">parseAndRender</span>(<span class="string">'{{name | capitalize}}'</span>, {<span class="attr">name</span>: <span class="string">'alice'</span>})</span><br><span class="line"> .<span class="title function_">then</span>(<span class="variable language_">console</span>.<span class="property">log</span>); <span class="comment">// outputs 'Alice'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">const</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
engine
|
||||
<span class="token punctuation">.</span><span class="token function">parseAndRender</span><span class="token punctuation">(</span><span class="token string">'{{name | capitalize}}'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>name<span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">}</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">.</span><span class="token function">then</span><span class="token punctuation">(</span><span class="token builtin">console</span><span class="token punctuation">.</span>log<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// outputs 'Alice'</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">Working Demo</strong><p>Here’s a working demo for LiquidJS usage in TypeScript: <a href="https://github.com/harttle/liquidjs/blob/master/demo/typescript/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/typescript/</a>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="LiquidJS-in-Browsers" class="article-heading"><a href="#LiquidJS-in-Browsers" class="headerlink" title="LiquidJS in Browsers"></a>LiquidJS in Browsers<a class="article-anchor" href="#LiquidJS-in-Browsers" aria-hidden="true"></a></h2><p>Pre-built UMD bundles are also available:</p>
|
||||
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment"><!--for production--></span></span><br><span class="line"><span class="tag"><<span class="name">script</span> <span class="attr">src</span>=<span class="string">"https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.min.js"</span>></span><span class="tag"></<span class="name">script</span>></span></span><br><span class="line"><span class="comment"><!--for development--></span></span><br><span class="line"><span class="tag"><<span class="name">script</span> <span class="attr">src</span>=<span class="string">"https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.umd.js"</span>></span><span class="tag"></<span class="name">script</span>></span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-markup" data-language="markup"><code class="language-markup"><span class="token comment"><!--for production--></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>script</span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.min.js<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token script"></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>script</span><span class="token punctuation">></span></span>
|
||||
<span class="token comment"><!--for development--></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>script</span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.umd.js<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token script"></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>script</span><span class="token punctuation">></span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">Working Demo</strong><p>Here’s a living demo on jsFiddle: <a href="https://jsfiddle.net/pd4jhzLs/1/" rel="external nofollow noreferrer" target="_blank">jsfiddle.net/pd4jhzLs/1/</a>, and the source code is also available in <a href="https://github.com/harttle/liquidjs/blob/master/demo/browser/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/browser/</a>.</p>
|
||||
</blockquote>
|
||||
@@ -117,30 +130,32 @@
|
||||
</blockquote>
|
||||
|
||||
<h2 id="LiquidJS-in-CLI" class="article-heading"><a href="#LiquidJS-in-CLI" class="headerlink" title="LiquidJS in CLI"></a>LiquidJS in CLI<a class="article-anchor" href="#LiquidJS-in-CLI" aria-hidden="true"></a></h2><p>LiquidJS can also be used to render a template directly from CLI using <code>npx</code>:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npx liquidjs --template <span class="string">'{{"hello" | capitalize}}'</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash">npx liquidjs <span class="token parameter variable">--template</span> <span class="token string">'{{"hello" | capitalize}}'</span><span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>You can either pass the template inline (as shown above) or you can read it from a file by using the <code>@</code> character followed by a path, like so:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npx liquidjs --template @./some-template.liquid</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash">npx liquidjs <span class="token parameter variable">--template</span> @./some-template.liquid<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>You can also use the <code>@-</code> syntax to read the template from <code>stdin</code>:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="built_in">echo</span> <span class="string">'{{"hello" | capitalize}}'</span> | npx liquidjs --template @-</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash"><span class="token builtin class-name">echo</span> <span class="token string">'{{"hello" | capitalize}}'</span> <span class="token operator">|</span> npx liquidjs <span class="token parameter variable">--template</span> @-<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>A context can be passed in the same ways (i.e. inline, from a path or piped through <code>stdin</code>). The following three are equivalent:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">npx liquidjs --template <span class="string">'Hello, {{ name }}!'</span> --context <span class="string">'{"name": "Snake"}'</span></span><br><span class="line">npx liquidjs --template <span class="string">'Hello, {{ name }}!'</span> --context @./some-context.json</span><br><span class="line"><span class="built_in">echo</span> <span class="string">'{"name": "Snake"}'</span> | npx liquidjs --template <span class="string">'Hello, {{ name }}!'</span> --context @-</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash">npx liquidjs <span class="token parameter variable">--template</span> <span class="token string">'Hello, {{ name }}!'</span> <span class="token parameter variable">--context</span> <span class="token string">'{"name": "Snake"}'</span>
|
||||
npx liquidjs <span class="token parameter variable">--template</span> <span class="token string">'Hello, {{ name }}!'</span> <span class="token parameter variable">--context</span> @./some-context.json
|
||||
<span class="token builtin class-name">echo</span> <span class="token string">'{"name": "Snake"}'</span> <span class="token operator">|</span> npx liquidjs <span class="token parameter variable">--template</span> <span class="token string">'Hello, {{ name }}!'</span> <span class="token parameter variable">--context</span> @-<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Note that you can only use the <code>stdin</code> specifier <code>@-</code> for a single argument. If you try to use it for both <code>--template</code> and <code>--context</code> you will get an error.</p>
|
||||
<p>The rendered output is written to <code>stdout</code> by default, but you can also specify an output file (if the file exists, it will be overwritten):</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npx liquidjs --template <span class="string">'{{"hello" | capitalize}}'</span> --output ./hello.txt</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash">npx liquidjs <span class="token parameter variable">--template</span> <span class="token string">'{{"hello" | capitalize}}'</span> <span class="token parameter variable">--output</span> ./hello.txt<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>You can also pass a number of options to customize template rendering behavior. For example, the <code>--js-truthy</code> option can be used to enable JavaScript truthiness:</p>
|
||||
<figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npx liquidjs --template @./some-template.liquid --js-truthy</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-bash" data-language="bash"><code class="language-bash">npx liquidjs <span class="token parameter variable">--template</span> @./some-template.liquid --js-truthy<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>Most of the <a href="./options.html">options available through the JavaScript API</a> are also available from the CLI. For help on available options, use <code>npx liquidjs --help</code>.</p>
|
||||
<h2 id="Miscellaneous" class="article-heading"><a href="#Miscellaneous" class="headerlink" title="Miscellaneous"></a>Miscellaneous<a class="article-anchor" href="#Miscellaneous" aria-hidden="true"></a></h2><p>A ReactJS demo is also added by <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/stevenanthonyrevo">@stevenanthonyrevo</a>, see <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/demo/reactjs/">liquidjs/demo/reactjs/</a>.</p>
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="intro-to-liquid.html" class="article-footer-prev" title="Intro to Liquid"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="options.html" class="article-footer-next" title="Options"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -110,7 +110,21 @@
|
||||
<li><code>evalValueSync()</code></li>
|
||||
</ul>
|
||||
<h2 id="Implement-Sync-Compatible-Tags" class="article-heading"><a href="#Implement-Sync-Compatible-Tags" class="headerlink" title="Implement Sync-Compatible Tags"></a>Implement Sync-Compatible Tags<a class="article-anchor" href="#Implement-Sync-Compatible-Tags" aria-hidden="true"></a></h2><p>LiquidJS uses a generator-based async implementation to support both async and sync in one piece of tag implementation. For example, below <code>UpperTag</code> can be used in both <code>engine.renderSync()</code> and <code>engine.render()</code>.</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">TagToken</span>, <span class="title class_">Context</span>, <span class="title class_">Emitter</span>, <span class="title class_">TopLevelToken</span>, <span class="title class_">Value</span>, <span class="title class_">Tag</span>, <span class="title class_">Liquid</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="comment">// Usage: {% upper "alice" %}</span></span><br><span class="line"><span class="comment">// Output: ALICE</span></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'upper'</span>, <span class="keyword">class</span> <span class="title class_">UpperTag</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Tag</span> {</span><br><span class="line"> <span class="keyword">private</span> <span class="attr">value</span>: <span class="title class_">Value</span></span><br><span class="line"> <span class="title function_">constructor</span> (<span class="params"><span class="attr">token</span>: <span class="title class_">TagToken</span>, <span class="attr">remainTokens</span>: <span class="title class_">TopLevelToken</span>[], <span class="attr">liquid</span>: <span class="title class_">Liquid</span></span>) {</span><br><span class="line"> <span class="variable language_">super</span>(token, remainTokens, liquid)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">value</span> = <span class="keyword">new</span> <span class="title class_">Value</span>(token.<span class="property">args</span>, liquid)</span><br><span class="line"> }</span><br><span class="line"> * <span class="title function_">render</span> (<span class="attr">ctx</span>: <span class="title class_">Context</span>, <span class="attr">emitter</span>: <span class="title class_">Emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> title = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">value</span>.<span class="title function_">value</span>(ctx)</span><br><span class="line"> emitter.<span class="title function_">write</span>(title.<span class="title function_">toUpperCase</span>())</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">{</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken<span class="token punctuation">,</span> Value<span class="token punctuation">,</span> Tag<span class="token punctuation">,</span> Liquid <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token comment">// Usage: {% upper "alice" %}</span>
|
||||
<span class="token comment">// Output: ALICE</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token keyword">class</span> <span class="token class-name">UpperTag</span> <span class="token keyword">extends</span> <span class="token class-name">Tag</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">private</span> value<span class="token operator">:</span> Value
|
||||
<span class="token function">constructor</span> <span class="token punctuation">(</span>token<span class="token operator">:</span> TagToken<span class="token punctuation">,</span> remainTokens<span class="token operator">:</span> TopLevelToken<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span> liquid<span class="token operator">:</span> Liquid<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> remainTokens<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Value</span><span class="token punctuation">(</span>token<span class="token punctuation">.</span>args<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token operator">*</span> <span class="token function">render</span> <span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">,</span> emitter<span class="token operator">:</span> Emitter<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> title <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>value<span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span>ctx<span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>title<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>All builtin tags are implemented this way and safe to use in both sync and async (I’ll call it <em>sync-compatible</em>). To make your custom tag <em>sync-compatible</em>, you’ll need to:</p>
|
||||
<ul>
|
||||
@@ -119,22 +133,54 @@
|
||||
<li>do not call any APIs that returns a Promise.</li>
|
||||
</ul>
|
||||
<h2 id="Call-APIs-that-return-a-Promise" class="article-heading"><a href="#Call-APIs-that-return-a-Promise" class="headerlink" title="Call APIs that return a Promise"></a>Call APIs that return a Promise<a class="article-anchor" href="#Call-APIs-that-return-a-Promise" aria-hidden="true"></a></h2><p>But LiquidJS is Promise-friendly, right? You can still call Promise-based functions and wait for that Promise within tag implementations. Just replace <code>await</code> with <code>yield</code>. e.g. we’re calling <code>fs.readFile()</code> which returns a <code>Promise</code>:</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">* <span class="title function_">render</span> (<span class="attr">ctx</span>: <span class="title class_">Context</span>, <span class="attr">emitter</span>: <span class="title class_">Emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> file = <span class="keyword">yield</span> <span class="variable language_">this</span>.<span class="property">value</span>.<span class="title function_">value</span>(ctx)</span><br><span class="line"> <span class="keyword">const</span> title = <span class="keyword">yield</span> fs.<span class="title function_">readFile</span>(file, <span class="string">'utf8'</span>)</span><br><span class="line"> emitter.<span class="title function_">write</span>(title.<span class="title function_">toUpperCase</span>())</span><br><span class="line">}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token operator">*</span> <span class="token function">render</span> <span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">,</span> emitter<span class="token operator">:</span> Emitter<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> file <span class="token operator">=</span> <span class="token keyword">yield</span> <span class="token keyword">this</span><span class="token punctuation">.</span>value<span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span>ctx<span class="token punctuation">)</span>
|
||||
<span class="token keyword">const</span> title <span class="token operator">=</span> <span class="token keyword">yield</span> fs<span class="token punctuation">.</span><span class="token function">readFile</span><span class="token punctuation">(</span>file<span class="token punctuation">,</span> <span class="token string">'utf8'</span><span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>title<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Now that this <code>* render()</code> calls an API that returns a Promise, so it’s no longer <em>sync-compatible</em>.</p>
|
||||
<blockquote class="note info"><strong class="note-title">Non Sync-Compatible Tags</strong><p>Non <em>sync-compatible</em> tags are also valid tags, will work just fine for asynchronous API calls. When called synchronously, tags that return a <code>Promise</code> will be rendered as <code>[object Promise]</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Convert-LiquidJS-async-Generator-to-Promise" class="article-heading"><a href="#Convert-LiquidJS-async-Generator-to-Promise" class="headerlink" title="Convert LiquidJS async Generator to Promise"></a>Convert LiquidJS async Generator to Promise<a class="article-anchor" href="#Convert-LiquidJS-async-Generator-to-Promise" aria-hidden="true"></a></h2><p>You can convert a Generator to Promise by <a href="/api/functions/toPromise.html">toPromise</a>, for example:</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { <span class="title class_">TagToken</span>, <span class="title class_">Context</span>, <span class="title class_">Emitter</span>, <span class="title class_">TopLevelToken</span>, <span class="title class_">Value</span>, <span class="title class_">Tag</span>, <span class="title class_">Liquid</span>, toPromise } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="comment">// Usage: {% upper "alice" %}</span></span><br><span class="line"><span class="comment">// Output: ALICE</span></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'upper'</span>, <span class="keyword">class</span> <span class="title class_">UpperTag</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Tag</span> {</span><br><span class="line"> <span class="keyword">private</span> <span class="attr">value</span>: <span class="title class_">Value</span></span><br><span class="line"> <span class="title function_">constructor</span> (<span class="params"><span class="attr">token</span>: <span class="title class_">TagToken</span>, <span class="attr">remainTokens</span>: <span class="title class_">TopLevelToken</span>[], <span class="attr">liquid</span>: <span class="title class_">Liquid</span></span>) {</span><br><span class="line"> <span class="variable language_">super</span>(token, remainTokens, liquid)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">value</span> = <span class="keyword">new</span> <span class="title class_">Value</span>(token.<span class="property">args</span>, liquid)</span><br><span class="line"> }</span><br><span class="line"> <span class="keyword">async</span> <span class="title function_">render</span> (<span class="attr">ctx</span>: <span class="title class_">Context</span>, <span class="attr">emitter</span>: <span class="title class_">Emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> title = <span class="keyword">await</span> <span class="title function_">toPromise</span>(<span class="variable language_">this</span>.<span class="property">value</span>.<span class="title function_">value</span>(ctx))</span><br><span class="line"> emitter.<span class="title function_">write</span>(title.<span class="title function_">toUpperCase</span>())</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">{</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken<span class="token punctuation">,</span> Value<span class="token punctuation">,</span> Tag<span class="token punctuation">,</span> Liquid<span class="token punctuation">,</span> toPromise <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token comment">// Usage: {% upper "alice" %}</span>
|
||||
<span class="token comment">// Output: ALICE</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token keyword">class</span> <span class="token class-name">UpperTag</span> <span class="token keyword">extends</span> <span class="token class-name">Tag</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">private</span> value<span class="token operator">:</span> Value
|
||||
<span class="token function">constructor</span> <span class="token punctuation">(</span>token<span class="token operator">:</span> TagToken<span class="token punctuation">,</span> remainTokens<span class="token operator">:</span> TopLevelToken<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span> liquid<span class="token operator">:</span> Liquid<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> remainTokens<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Value</span><span class="token punctuation">(</span>token<span class="token punctuation">.</span>args<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token keyword">async</span> <span class="token function">render</span> <span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">,</span> emitter<span class="token operator">:</span> Emitter<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> title <span class="token operator">=</span> <span class="token keyword">await</span> <span class="token function">toPromise</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>value<span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span>ctx<span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span>title<span class="token punctuation">.</span><span class="token function">toUpperCase</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Async-only-Tags" class="article-heading"><a href="#Async-only-Tags" class="headerlink" title="Async only Tags"></a>Async only Tags<a class="article-anchor" href="#Async-only-Tags" aria-hidden="true"></a></h2><p>If your tag is intend to be used only asynchronously, it can be declared as <code>async render()</code> so you can use <code>await</code> in its implementation directly:</p>
|
||||
<figure class="highlight typescript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> { toPromise, <span class="title class_">TagToken</span>, <span class="title class_">Context</span>, <span class="title class_">Emitter</span>, <span class="title class_">TopLevelToken</span>, <span class="title class_">Value</span>, <span class="title class_">Tag</span>, <span class="title class_">Liquid</span> } <span class="keyword">from</span> <span class="string">'liquidjs'</span></span><br><span class="line"></span><br><span class="line"><span class="comment">// Usage: {% upper "alice" %}</span></span><br><span class="line"><span class="comment">// Output: ALICE</span></span><br><span class="line">engine.<span class="title function_">registerTag</span>(<span class="string">'upper'</span>, <span class="keyword">class</span> <span class="title class_">UpperTag</span> <span class="keyword">extends</span> <span class="title class_ inherited__">Tag</span> {</span><br><span class="line"> <span class="keyword">private</span> <span class="attr">value</span>: <span class="title class_">Value</span></span><br><span class="line"> <span class="title function_">constructor</span> (<span class="params"><span class="attr">token</span>: <span class="title class_">TagToken</span>, <span class="attr">remainTokens</span>: <span class="title class_">TopLevelToken</span>[], <span class="attr">liquid</span>: <span class="title class_">Liquid</span></span>) {</span><br><span class="line"> <span class="variable language_">super</span>(token, remainTokens, liquid)</span><br><span class="line"> <span class="variable language_">this</span>.<span class="property">value</span> = <span class="keyword">new</span> <span class="title class_">Value</span>(token.<span class="property">args</span>, liquid)</span><br><span class="line"> }</span><br><span class="line"> <span class="keyword">async</span> <span class="title function_">render</span> (<span class="attr">ctx</span>: <span class="title class_">Context</span>, <span class="attr">emitter</span>: <span class="title class_">Emitter</span>) {</span><br><span class="line"> <span class="keyword">const</span> title = <span class="keyword">await</span> <span class="title function_">toPromise</span>(<span class="variable language_">this</span>.<span class="property">value</span>.<span class="title function_">value</span>(ctx))</span><br><span class="line"> emitter.<span class="title function_">write</span>(<span class="string">`<h1><span class="subst">${title}</span></h1>`</span>)</span><br><span class="line"> }</span><br><span class="line">})</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">{</span> toPromise<span class="token punctuation">,</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken<span class="token punctuation">,</span> Value<span class="token punctuation">,</span> Tag<span class="token punctuation">,</span> Liquid <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
|
||||
|
||||
<span class="token comment">// Usage: {% upper "alice" %}</span>
|
||||
<span class="token comment">// Output: ALICE</span>
|
||||
engine<span class="token punctuation">.</span><span class="token function">registerTag</span><span class="token punctuation">(</span><span class="token string">'upper'</span><span class="token punctuation">,</span> <span class="token keyword">class</span> <span class="token class-name">UpperTag</span> <span class="token keyword">extends</span> <span class="token class-name">Tag</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">private</span> value<span class="token operator">:</span> Value
|
||||
<span class="token function">constructor</span> <span class="token punctuation">(</span>token<span class="token operator">:</span> TagToken<span class="token punctuation">,</span> remainTokens<span class="token operator">:</span> TopLevelToken<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">,</span> liquid<span class="token operator">:</span> Liquid<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">super</span><span class="token punctuation">(</span>token<span class="token punctuation">,</span> remainTokens<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token keyword">this</span><span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Value</span><span class="token punctuation">(</span>token<span class="token punctuation">.</span>args<span class="token punctuation">,</span> liquid<span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token keyword">async</span> <span class="token function">render</span> <span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">,</span> emitter<span class="token operator">:</span> Emitter<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token keyword">const</span> title <span class="token operator">=</span> <span class="token keyword">await</span> <span class="token function">toPromise</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>value<span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span>ctx<span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
emitter<span class="token punctuation">.</span><span class="token function">write</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string"><h1></span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>title<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"></h1></span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="drops.html" class="article-footer-prev" title="Liquid Drops"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="whitespace-control.html" class="article-footer-next" title="Whitespace Control"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -226,7 +226,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="operators.html" class="article-footer-prev" title="Operators"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="dos.html" class="article-footer-next" title="DoS"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -93,27 +93,48 @@
|
||||
</header>
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>LiquidJS is compatible to the <a target="_blank" rel="noopener external nofollow noreferrer" href="https://expressjs.com/en/resources/template-engines.html">express template engines</a>. You can set liquidjs instance to the <a target="_blank" rel="noopener external nofollow noreferrer" href="https://expressjs.com/en/guide/using-template-engines.html">view engine</a> option:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>);</span><br><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>();</span><br><span class="line"></span><br><span class="line"><span class="comment">// register liquid engine</span></span><br><span class="line">app.<span class="title function_">engine</span>(<span class="string">'liquid'</span>, engine.<span class="title function_">express</span>()); </span><br><span class="line">app.<span class="title function_">set</span>(<span class="string">'views'</span>, <span class="string">'./views'</span>); <span class="comment">// specify the views directory</span></span><br><span class="line">app.<span class="title function_">set</span>(<span class="string">'view engine'</span>, <span class="string">'liquid'</span>); <span class="comment">// set liquid to default</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">// register liquid engine</span>
|
||||
app<span class="token punctuation">.</span><span class="token function">engine</span><span class="token punctuation">(</span><span class="token string">'liquid'</span><span class="token punctuation">,</span> engine<span class="token punctuation">.</span><span class="token function">express</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
app<span class="token punctuation">.</span><span class="token function">set</span><span class="token punctuation">(</span><span class="token string">'views'</span><span class="token punctuation">,</span> <span class="token string">'./views'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// specify the views directory</span>
|
||||
app<span class="token punctuation">.</span><span class="token function">set</span><span class="token punctuation">(</span><span class="token string">'view engine'</span><span class="token punctuation">,</span> <span class="token string">'liquid'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// set liquid to default</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<blockquote class="note info"><strong class="note-title">Working Demo</strong><p>Here’s a working demo for LiquidJS usage in Express.js: <a href="https://github.com/harttle/liquidjs/blob/master/demo/express/" rel="external nofollow noreferrer" target="_blank">liquidjs/demo/express/</a>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="Template-Lookup" class="article-heading"><a href="#Template-Lookup" class="headerlink" title="Template Lookup"></a>Template Lookup<a class="article-anchor" href="#Template-Lookup" aria-hidden="true"></a></h2><p>The <a href="/api/interfaces/LiquidOptions.html#root">root</a> option will continue to work as templates root, as you can see in <a href="./render-a-file.html">Render A Template File</a>. Additionally, the <a target="_blank" rel="noopener external nofollow noreferrer" href="https://expressjs.com/en/guide/using-template-engines.html"><code>views</code></a> option in express.js (as shown above) will also be respected. Say you have a template directory like:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">.</span><br><span class="line">├── views1/</span><br><span class="line">│ └── hello.liquid</span><br><span class="line">└── views2/</span><br><span class="line"> └── world.liquid</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">.
|
||||
├── views1/
|
||||
│ └── hello.liquid
|
||||
└── views2/
|
||||
└── world.liquid<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>And you’re setting template root for liquidjs to <code>views1</code> and expressjs to <code>views2</code>:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>);</span><br><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">root</span>: <span class="string">'./views1/'</span></span><br><span class="line">});</span><br><span class="line"></span><br><span class="line">app.<span class="title function_">engine</span>(<span class="string">'liquid'</span>, engine.<span class="title function_">express</span>()); </span><br><span class="line">app.<span class="title function_">set</span>(<span class="string">'views'</span>, <span class="string">'./views2'</span>); <span class="comment">// specify the views directory</span></span><br><span class="line">app.<span class="title function_">set</span>(<span class="string">'view engine'</span>, <span class="string">'liquid'</span>); <span class="comment">// set liquid to default</span></span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token string">'./views1/'</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
app<span class="token punctuation">.</span><span class="token function">engine</span><span class="token punctuation">(</span><span class="token string">'liquid'</span><span class="token punctuation">,</span> engine<span class="token punctuation">.</span><span class="token function">express</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
app<span class="token punctuation">.</span><span class="token function">set</span><span class="token punctuation">(</span><span class="token string">'views'</span><span class="token punctuation">,</span> <span class="token string">'./views2'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// specify the views directory</span>
|
||||
app<span class="token punctuation">.</span><span class="token function">set</span><span class="token punctuation">(</span><span class="token string">'view engine'</span><span class="token punctuation">,</span> <span class="token string">'liquid'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// set liquid to default</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Both of <code>hello.liquid</code> and <code>world.liquid</code> can be resolved and rendered:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">res.<span class="title function_">render</span>(<span class="string">'hello'</span>)</span><br><span class="line">res.<span class="title function_">render</span>(<span class="string">'world'</span>)</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript">res<span class="token punctuation">.</span><span class="token function">render</span><span class="token punctuation">(</span><span class="token string">'hello'</span><span class="token punctuation">)</span>
|
||||
res<span class="token punctuation">.</span><span class="token function">render</span><span class="token punctuation">(</span><span class="token string">'world'</span><span class="token punctuation">)</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<h2 id="Caching" class="article-heading"><a href="#Caching" class="headerlink" title="Caching"></a>Caching<a class="article-anchor" href="#Caching" aria-hidden="true"></a></h2><p>Simply setting the <a href="/api/interfaces/LiquidOptions.html#cache">cache option</a> to true will enable template caching, as explained in <a href="./caching.html">Caching</a>. It’s recommended to enable cache in production environment, which can be done by:</p>
|
||||
<figure class="highlight javascript"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">var</span> { <span class="title class_">Liquid</span> } = <span class="built_in">require</span>(<span class="string">'liquidjs'</span>);</span><br><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> <span class="title class_">Liquid</span>({</span><br><span class="line"> <span class="attr">cache</span>: process.<span class="property">env</span>.<span class="property">NODE_ENV</span> === <span class="string">'production'</span></span><br><span class="line">});</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-javascript" data-language="javascript"><code class="language-javascript"><span class="token keyword">var</span> <span class="token punctuation">{</span> Liquid <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">'liquidjs'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">var</span> engine <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Liquid</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
||||
<span class="token literal-property property">cache</span><span class="token operator">:</span> process<span class="token punctuation">.</span>env<span class="token punctuation">.</span><span class="token constant">NODE_ENV</span> <span class="token operator">===</span> <span class="token string">'production'</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span><span></span><span></span></span></code></pre>
|
||||
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="partials-and-layouts.html" class="article-footer-prev" title="Includes and Layouts"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="caching.html" class="article-footer-next" title="Caching"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
@@ -94,16 +94,19 @@
|
||||
<div class="article-content" itemprop="articleBody">
|
||||
<p>To keep source code neat and indented, we’re adding spaces to our templates. LiquidJS offers whitespace control capabilities to eliminate these unwanted whitespaces in output HTML.</p>
|
||||
<h2 id="via-Markups" class="article-heading"><a href="#via-Markups" class="headerlink" title="via Markups"></a>via Markups<a class="article-anchor" href="#via-Markups" aria-hidden="true"></a></h2><p>By default, all tags and output markups lines will generate a NL (<code>\n</code>), and whitespaces if there’s any indentation. For example:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">{% author = "harttle" %}</span><br><span class="line">{{ author }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> author <span class="token operator">=</span> <span class="token string">"harttle"</span> <span class="token delimiter punctuation">%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> author <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Outputs (note the blank link):</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"></span><br><span class="line">harttle</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">
|
||||
harttle<span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>We can include hyphens in your tag syntax (<code>{{-</code>, <code>-}}</code>, <code>{%-</code>, <code>-%}</code>) to strip whitespace from left or right. For example:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">{% assign author = "harttle" -%}</span><br><span class="line">{{ author }}</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-liquid" data-language="liquid"><code class="language-liquid"><span class="token liquid language-liquid"><span class="token delimiter punctuation">{%</span> <span class="token keyword">assign</span> author <span class="token operator">=</span> <span class="token string">"harttle"</span> <span class="token delimiter punctuation">-%}</span></span>
|
||||
<span class="token liquid language-liquid"><span class="token delimiter punctuation">{{</span> author <span class="token delimiter punctuation">}}</span></span><span aria-hidden="true" class="line-numbers-rows"><span></span><span></span></span></code></pre>
|
||||
|
||||
<p>Outputs:</p>
|
||||
<figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">harttle</span><br></pre></td></tr></table></figure>
|
||||
<pre class="line-numbers language-none"><code class="language-none">harttle<span aria-hidden="true" class="line-numbers-rows"><span></span></span></code></pre>
|
||||
|
||||
<p>In this case, the <code>-%}</code> strips the whitespace from the right side of the <code>assign</code> tag.</p>
|
||||
<h2 id="via-Options" class="article-heading"><a href="#via-Options" class="headerlink" title="via Options"></a>via Options<a class="article-anchor" href="#via-Options" aria-hidden="true"></a></h2><p>Alternatively, LiquidJS provides these per engine options to enable whitespace control without sweeping changes of your templates:</p>
|
||||
@@ -118,7 +121,7 @@
|
||||
|
||||
</div>
|
||||
<footer class="article-footer">
|
||||
<time class="article-footer-updated" datetime="2024-08-19T19:36:26.426Z" itemprop="dateModified">Last updated: 2024-08-19</time>
|
||||
<time class="article-footer-updated" datetime="2024-08-20T01:26:05.764Z" itemprop="dateModified">Last updated: 2024-08-20</time>
|
||||
<a href="sync-and-async.html" class="article-footer-prev" title="Sync and Async"><i class="icon-chevron-left"></i><span>Prev</span></a><a href="plugins.html" class="article-footer-next" title="Plugins"><span>Next</span><i class="icon-chevron-right"></i></a>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user