<ahref="use-in-expressjs.html"class="article-footer-prev"title="Use in Express.js"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="register-filters-tags.html"class="article-footer-next"title="Register Filters/Tags"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="truthy-and-falsy.html"class="article-footer-prev"title="Truthy and Falsy"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="changelog.html"class="article-footer-next"title="Changelog"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="plugins.html"class="article-footer-prev"title="Plugins"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="truthy-and-falsy.html"class="article-footer-next"title="Truthy and Falsy"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="access-scope-in-filters.html"class="article-footer-prev"title="Access Scope in Filters"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="render-tag-content.html"class="article-footer-next"title="Render Tag Content"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="render-file.html"class="article-footer-prev"title="Render Files"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="use-in-expressjs.html"class="article-footer-next"title="Use in Express.js"><span>Next</span><iclass="icon-chevron-right"></i></a>
<h2id="Unregister-Tags-Filters"class="article-heading"><ahref="#Unregister-Tags-Filters"class="headerlink"title="Unregister Tags/Filters"></a>Unregister Tags/Filters<aclass="article-anchor"href="#Unregister-Tags-Filters"aria-hidden="true"></a></h2><p>In some cases it’s desirable to disable some tags/filters (see <atarget="_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>
<preclass="line-numbers language-javascript"data-language="javascript"><codeclass="language-javascript"><spanclass="token comment">// disable a tag</span>
<ahref="caching.html"class="article-footer-prev"title="Caching"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="access-scope-in-filters.html"class="article-footer-next"title="Access Scope in Filters"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="options.html"class="article-footer-prev"title="Options"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="partials-and-layouts.html"class="article-footer-next"title="Includes and Layouts"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="parse-parameters.html"class="article-footer-prev"title="Parse Parameters"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="sync-and-async.html"class="article-footer-next"title="Sync and Async"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="intro-to-liquid.html"class="article-footer-prev"title="Intro to Liquid"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="options.html"class="article-footer-next"title="Options"><span>Next</span><iclass="icon-chevron-right"></i></a>
<h2id="Implement-Sync-Compatible-Tags"class="article-heading"><ahref="#Implement-Sync-Compatible-Tags"class="headerlink"title="Implement Sync-Compatible Tags"></a>Implement Sync-Compatible Tags<aclass="article-anchor"href="#Implement-Sync-Compatible-Tags"aria-hidden="true"></a></h2><h3id="Requirements"class="article-heading"><ahref="#Requirements"class="headerlink"title="Requirements"></a>Requirements<aclass="article-anchor"href="#Requirements"aria-hidden="true"></a></h3><p>All builtin tags are <em>sync-compatible</em> and safe to use for both sync and async APIs. To make your custom tag<em>sync-compatible</em>, you’ll need to avoid return a <code>Promise</code>. That means the <code>render(context, emitter)</code>:</p>
<h2id="Implement-Sync-Compatible-Tags"class="article-heading"><ahref="#Implement-Sync-Compatible-Tags"class="headerlink"title="Implement Sync-Compatible Tags"></a>Implement Sync-Compatible Tags<aclass="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>
<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>
<li>Should not directly <code>return <Promise></code>, and</li>
<li>Should not be declared as <code>async</code>.</li>
<li>declare render function as <code>* render()</code>, in which</li>
<li>do not directly <code>return <Promise></code>, and</li>
<li>do not call any APIs that returns a Promise.</li>
</ul>
<h2id="Call-APIs-that-return-a-Promise"class="article-heading"><ahref="#Call-APIs-that-return-a-Promise"class="headerlink"title="Call APIs that return a Promise"></a>Call APIs that return a Promise<aclass="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>
<p>Now that this <code>* render()</code> calls an API that returns a Promise, so it’s no longer <em>sync-compatible</em>.</p>
<blockquoteclass="note info"><strongclass="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>
<h3id="Await-Promises"class="article-heading"><ahref="#Await-Promises"class="headerlink"title="Await Promises"></a>Await Promises<aclass="article-anchor"href="#Await-Promises"aria-hidden="true"></a></h3><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> and keep <code>* render()</code> instead of <code>async render()</code>. e.g.</p>
<h2id="Convert-LiquidJS-async-Generator-to-Promise"class="article-heading"><ahref="#Convert-LiquidJS-async-Generator-to-Promise"class="headerlink"title="Convert LiquidJS async Generator to Promise"></a>Convert LiquidJS async Generator to Promise<aclass="article-anchor"href="#Convert-LiquidJS-async-Generator-to-Promise"aria-hidden="true"></a></h2><p>You can convert a Generator to Promise by <ahref="/api/modules/liquid_.html#toPromise">toPromise</a>, for example:</p>
<p>See this JSFiddle: <atarget="_blank"rel="noopener external nofollow noreferrer"href="http://jsfiddle.net/ctj364up/6/">http://jsfiddle.net/ctj364up/6/</a>.</p>
<h2id="Async-only-Tags"class="article-heading"><ahref="#Async-only-Tags"class="headerlink"title="Async-only Tags"></a>Async-only Tags<aclass="article-anchor"href="#Async-only-Tags"aria-hidden="true"></a></h2><p>For tags that intended to be used only by async API, or those cannot be implemented synchronously, there’s no difference between using generator-base syntax or async syntax. I’ll call them <em>async-only tags</em>.</p>
<p>For example, if the above <code>this.liquid._evalValue()</code> doesn’t respect <code>ctx.sync</code> and always returns a Promise, even if the tag is implemented using <code>* render()</code> and <code>yield this.liquid._evalValue()</code>, it will be rendered as <code><object Promise></code> anyway.</p>
<p>For <em>async-only tags</em>, you can use async syntax at will. Be careful some APIs in LiquidJS return Promises and others return Generators. You’ll need <ahref="/api/modules/liquid_.html#toPromise">toPromise</a> API to convert a Generator to a Promise, for example:</p>
<h2id="Async-only-Tags"class="article-heading"><ahref="#Async-only-Tags"class="headerlink"title="Async only Tags"></a>Async only Tags<aclass="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>
<ahref="render-tag-content.html"class="article-footer-prev"title="Render Tag Content"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="whitespace-control.html"class="article-footer-next"title="Whitespace Control"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="operators.html"class="article-footer-prev"title="Operators"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="migrate-to-9.html"class="article-footer-next"title="Migrate to LiquidJS 9"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="partials-and-layouts.html"class="article-footer-prev"title="Includes and Layouts"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="caching.html"class="article-footer-next"title="Caching"><span>Next</span><iclass="icon-chevron-right"></i></a>
<ahref="sync-and-async.html"class="article-footer-prev"title="Sync and Async"><iclass="icon-chevron-left"></i><span>Prev</span></a><ahref="plugins.html"class="article-footer-next"title="Plugins"><span>Next</span><iclass="icon-chevron-right"></i></a>
</footer>
</div>
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
harttle