Files
liquidjs/tutorials/sync-and-async.html
T

242 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>Sync and Async | LiquidJS</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="LiquidJS is a simple, expressive and safe Shopify / Github Pages compatible template engine in pure JavaScript.">
<link rel="dns-prefetch" href="https://cdn.jsdelivr.net/">
<link rel="manifest" href="/manifest.json">
<!-- Canonical links -->
<link rel="canonical" href="https://liquidjs.com/tutorials/sync-and-async.html">
<!-- Alternative links -->
<link rel="alternative" hreflang="en" href="https://liquidjs.com/tutorials/sync-and-async">
<link rel="alternative" hreflang="zh-cn" href="https://liquidjs.com/zh-cn/tutorials/sync-and-async">
<!-- Icon -->
<link rel="apple-touch-icon" sizes="57x57" href="../icon/apple-touch-icon-57x57.png">
<link rel="apple-touch-icon" sizes="114x114" href="../icon/apple-touch-icon-114x114.png">
<link rel="apple-touch-icon" sizes="72x72" href="../icon/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon" sizes="144x144" href="../icon/apple-touch-icon-144x144.png">
<link rel="apple-touch-icon" sizes="60x60" href="../icon/apple-touch-icon-60x60.png">
<link rel="apple-touch-icon" sizes="120x120" href="../icon/apple-touch-icon-120x120.png">
<link rel="apple-touch-icon" sizes="76x76" href="../icon/apple-touch-icon-76x76.png">
<link rel="apple-touch-icon" sizes="152x152" href="../icon/apple-touch-icon-152x152.png">
<link rel="icon" type="image/png" href="../icon/favicon-196x196.png" sizes="196x196">
<link rel="icon" type="image/png" href="../icon/favicon-160x160.png" sizes="160x160">
<link rel="icon" type="image/png" href="../icon/favicon-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="../icon/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="../icon/favicon-32x32.png" sizes="32x32">
<meta name="msapplication-TileColor" content="#2f83cd">
<meta name="msapplication-TileImage" content="../icon/mstile-144x144.png">
<link rel="stylesheet" href="../css/navy.css">
<link rel="alternate" href="../atom.xml" title="LiquidJS" type="application/atom+xml">
<meta name="generator" content="Hexo 5.4.0"></head>
<body>
<div id="container">
<header id="header" class="wrapper">
<div id="header-inner" class="inner">
<h1 id="logo-wrap">
<a href="../index.html" id="logo">LiquidJS</a>
</h1>
<nav id="main-nav">
<a href="../tutorials/intro-to-liquid.html" class="main-nav-link">Tutorials</a><a href="../tags/overview.html" class="main-nav-link">Tags</a><a href="../filters/overview.html" class="main-nav-link">Filters</a><a href="../playground.html" class="main-nav-link">Playground</a><a href="../api/classes/liquid_.liquid.html" class="main-nav-link">API</a>
<div id="search-input-wrap">
<i id="search-input-icon" class="icon-search"></i>
<input type="search" id="search-input" placeholder="Search...">
</div>
</nav>
<div class="main-nav-link icon-nav-link">
<label><i class="icon-network"></i> <span class="icon-nav-title">English</span></label>
<select id="lang-select" data-canonical="tutorials/sync-and-async.html">
<option value="en" selected>English</option>
<option value="zh-cn">简体中文</option>
</select>
</div>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs" class="main-nav-link icon-nav-link"><i class="icon-github"></i> <span class="icon-nav-title">Github</span></a>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://opencollective.com/liquidjs" class="main-nav-link icon-nav-link"><i class="icon-opencollective"></i> <span class="icon-nav-title">Support</span></a>
<a id="mobile-nav-toggle">
<span class="mobile-nav-toggle-bar"></span>
<span class="mobile-nav-toggle-bar"></span>
<span class="mobile-nav-toggle-bar"></span>
</a>
</div>
</header>
<div id="content-wrap">
<div id="content" class="wrapper">
<div id="content-inner">
<aside id="sidebar" role="navigation">
<div class="inner">
<strong class="sidebar-title">Getting Started</strong><a href="intro-to-liquid.html" class="sidebar-link">Intro to Liquid</a><a href="setup.html" class="sidebar-link">Setup</a><a href="options.html" class="sidebar-link">Options</a><a href="render-file.html" class="sidebar-link">Render Files</a><a href="partials-and-layouts.html" class="sidebar-link">Includes and Layouts</a><a href="use-in-expressjs.html" class="sidebar-link">Use in Express.js</a><strong class="sidebar-title">Advanced</strong><a href="caching.html" class="sidebar-link">Caching</a><a href="register-filters-tags.html" class="sidebar-link">Register Filters/Tags</a><a href="access-scope-in-filters.html" class="sidebar-link">Access Scope in Filters</a><a href="parse-parameters.html" class="sidebar-link">Parse Parameters</a><a href="render-tag-content.html" class="sidebar-link">Render Tag Content</a><a href="sync-and-async.html" class="sidebar-link current">Sync and Async</a><a href="whitespace-control.html" class="sidebar-link">Whitespace Control</a><a href="plugins.html" class="sidebar-link">Plugins</a><a href="operators.html" class="sidebar-link">Operators</a><a href="truthy-and-falsy.html" class="sidebar-link">Truthy and Falsy</a><strong class="sidebar-title">Miscellaneous</strong><a href="migrate-to-9.html" class="sidebar-link">Migrate to LiquidJS 9</a><a href="changelog.html" class="sidebar-link">Changelog</a><a href="differences.html" class="sidebar-link">Differences with Shopify/liquid</a><a href="contribution-guidelines.html" class="sidebar-link">Contribution Guidelines</a>
</div>
</aside>
<article class="article-container" itemscope itemtype="http://schema.org/Article">
<div class="article-inner">
<div class="article">
<div class="inner">
<header class="article-header">
<h1 class="article-title" itemprop="name">Sync and Async</h1>
<a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/edit/master/docs/source/tutorials/sync-and-async.md" class="article-edit-link" title="Improve this doc"><i class="icon-pencil"></i></a>
</header>
<div class="article-content" itemprop="articleBody">
<p>LiquidJS supports both sync and async evaluate, and can be used with Promises. To reuse the same set of tag/filter implementations in both sync and async, LiquidJS tags are implemented as generators.</p>
<h2 id="Sync-and-Async-API" class="article-heading"><a href="#Sync-and-Async-API" class="headerlink" title="Sync and Async API"></a>Sync and Async API<a class="article-anchor" href="#Sync-and-Async-API" aria-hidden="true"></a></h2><p>All major methods on <a href="/api/classes/liquid_.liquid.html">Liquid</a> supports both sync and async. These methods return Promises:</p>
<ul>
<li><code>render()</code></li>
<li><code>renderFile()</code></li>
<li><code>parseFile()</code></li>
<li><code>parseAndRender()</code></li>
<li><code>evalValue()</code></li>
</ul>
<p>The synchronous version of methods contains a <code>Sync</code> suffix:</p>
<ul>
<li><code>renderSync()</code></li>
<li><code>renderFileSync()</code></li>
<li><code>parseFileSync()</code></li>
<li><code>parseAndRenderSync()</code></li>
<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><h3 id="Requirements" class="article-heading"><a href="#Requirements" class="headerlink" title="Requirements"></a>Requirements<a class="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>, youll need to avoid return a <code>Promise</code>. That means the <code>render(context, emitter)</code>:</p>
<ul>
<li>Should not directly <code>return &lt;Promise&gt;</code>, and</li>
<li>Should not be declared as <code>async</code>.</li>
</ul>
<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>
<h3 id="Await-Promises" class="article-heading"><a href="#Await-Promises" class="headerlink" title="Await Promises"></a>Await Promises<a class="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>
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">&#123;</span> TagToken<span class="token punctuation">,</span> Context<span class="token punctuation">,</span> Emitter<span class="token punctuation">,</span> TopLevelToken <span class="token punctuation">&#125;</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
<span class="token comment">// Usage: &#123;% upper "alice" %&#125;</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 punctuation">&#123;</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">&#123;</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>str <span class="token operator">=</span> tagToken<span class="token punctuation">.</span>args
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token operator">*</span> <span class="token function-variable function">render</span><span class="token operator">:</span> <span class="token keyword">function</span><span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token comment">// _evalValue will behave synchronously when called by synchronous API</span>
<span class="token comment">// in which case `ctx.sync == true`</span>
<span class="token keyword">var</span> str <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><span class="token function">_evalValue</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>str<span class="token punctuation">,</span> ctx<span class="token punctuation">)</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 punctuation">&#125;</span>
<span class="token punctuation">&#125;</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>See this JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="http://jsfiddle.net/ctj364up/6/">http://jsfiddle.net/ctj364up/6/</a>.</p>
<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>For tags that intended to be used only by async API, or those cannot be implemented synchronously, theres no difference between using generator-base syntax or async syntax. Ill call them <em>async-only tags</em>.</p>
<p>For example, if the above <code>this.liquid._evalValue()</code> doesnt 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>&lt;object Promise&gt;</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. Youll need <a href="/api/modules/liquid_.html#toPromise">toPromise</a> API to convert a Generator to a Promise, for example:</p>
<pre class="line-numbers language-typescript" data-language="typescript"><code class="language-typescript"><span class="token keyword">import</span> <span class="token punctuation">&#123;</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> toPromise <span class="token punctuation">&#125;</span> <span class="token keyword">from</span> <span class="token string">'liquidjs'</span>
<span class="token comment">// Usage: &#123;% upper "alice" %&#125;</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 punctuation">&#123;</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">&#123;</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>str <span class="token operator">=</span> tagToken<span class="token punctuation">.</span>args<span class="token punctuation">;</span> <span class="token comment">// name</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token function-variable function">render</span><span class="token operator">:</span> <span class="token keyword">async</span> <span class="token keyword">function</span><span class="token punctuation">(</span>ctx<span class="token operator">:</span> Context<span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">var</span> str <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>liquid<span class="token punctuation">.</span><span class="token function">_evalValue</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span>str<span class="token punctuation">,</span> ctx<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Or use the alternate API that returns a Promise</span>
<span class="token comment">// var str = await this.liquid.evalValue(this.str, ctx);</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 punctuation">&#125;</span>
<span class="token punctuation">&#125;</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>See this JSFiddle: <a target="_blank" rel="noopener external nofollow noreferrer" href="http://jsfiddle.net/ctj364up/5/">http://jsfiddle.net/ctj364up/5/</a>.</p>
</div>
<footer class="article-footer">
<time class="article-footer-updated" datetime="2022-11-14T09:25:10.400Z" itemprop="dateModified">Last updated: 2022-11-14</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="whitespace-control.html" class="article-footer-next" title="Whitespace Control"><span>Next</span><i class="icon-chevron-right"></i></a>
</footer>
</div>
</div>
<aside id="article-toc" role="navigation">
<div id="article-toc-inner">
<div id="article-toc-inner-list">
<strong class="sidebar-title">Contents</strong>
<ol class="toc"><li class="toc-item toc-level-2"><a class="toc-link" href="#Sync-and-Async-API"><span class="toc-text">Sync and Async API</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#Implement-Sync-Compatible-Tags"><span class="toc-text">Implement Sync-Compatible Tags</span></a><ol class="toc-child"><li class="toc-item toc-level-3"><a class="toc-link" href="#Requirements"><span class="toc-text">Requirements</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#Await-Promises"><span class="toc-text">Await Promises</span></a></li></ol></li><li class="toc-item toc-level-2"><a class="toc-link" href="#Async-only-Tags"><span class="toc-text">Async-only Tags</span></a></li></ol>
</div>
<a href="#" id="article-toc-top">Back to Top</a>
</div>
</aside>
</div>
</article>
</div>
</div>
</div>
<footer id="footer" class="wrapper">
<div class="inner">
<div id="footer-copyright">
&copy; 2022 <a href="https://github.com/harttle/liquidjs/graphs/contributors" rel="external nofollow noreferrer" target="_blank">Harttle</a><br>
Documentation licensed under <a href="http://creativecommons.org/licenses/by/4.0/" rel="external nofollow noreferrer" target="_blank">CC BY 4.0</a>.
</div>
<div id="footer-links">
<a href="https://twitter.com/harttleharttle" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-twitter"></i></a>
<a href="https://www.patreon.com/harttle" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-patreon"></i></a>
<a href="https://opencollective.com/liquidjs" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-opencollective"></i></a>
<a href="https://github.com/harttle/liquidjs" rel="external nofollow noreferrer" class="footer-link" target="_blank"><i class="icon-github"></i></a>
</div>
</div>
</footer>
</div>
<div id="mobile-nav-dimmer"></div>
<nav id="mobile-nav">
<div id="mobile-nav-inner">
<ul id="mobile-nav-list">
<a href="../tutorials/intro-to-liquid.html" class="mobile-nav-link">Tutorials</a><a href="../tags/overview.html" class="mobile-nav-link">Tags</a><a href="../filters/overview.html" class="mobile-nav-link">Filters</a><a href="../playground.html" class="mobile-nav-link">Playground</a><a href="../api/classes/liquid_.liquid.html" class="mobile-nav-link">API</a>
</ul>
<div class="mobile-sidebar-list">
<strong class="mobile-nav-title">Getting Started</strong><a href="intro-to-liquid.html" class="mobile-nav-link">Intro to Liquid</a><a href="setup.html" class="mobile-nav-link">Setup</a><a href="options.html" class="mobile-nav-link">Options</a><a href="render-file.html" class="mobile-nav-link">Render Files</a><a href="partials-and-layouts.html" class="mobile-nav-link">Includes and Layouts</a><a href="use-in-expressjs.html" class="mobile-nav-link">Use in Express.js</a><strong class="mobile-nav-title">Advanced</strong><a href="caching.html" class="mobile-nav-link">Caching</a><a href="register-filters-tags.html" class="mobile-nav-link">Register Filters/Tags</a><a href="access-scope-in-filters.html" class="mobile-nav-link">Access Scope in Filters</a><a href="parse-parameters.html" class="mobile-nav-link">Parse Parameters</a><a href="render-tag-content.html" class="mobile-nav-link">Render Tag Content</a><a href="sync-and-async.html" class="mobile-nav-link current">Sync and Async</a><a href="whitespace-control.html" class="mobile-nav-link">Whitespace Control</a><a href="plugins.html" class="mobile-nav-link">Plugins</a><a href="operators.html" class="mobile-nav-link">Operators</a><a href="truthy-and-falsy.html" class="mobile-nav-link">Truthy and Falsy</a><strong class="mobile-nav-title">Miscellaneous</strong><a href="migrate-to-9.html" class="mobile-nav-link">Migrate to LiquidJS 9</a><a href="changelog.html" class="mobile-nav-link">Changelog</a><a href="differences.html" class="mobile-nav-link">Differences with Shopify/liquid</a><a href="contribution-guidelines.html" class="mobile-nav-link">Contribution Guidelines</a>
</div>
</div>
<div id="mobile-button-list">
<a href="https://github.com/harttle/liquidjs" class="mobile-nav-link" rel="external" target="_blank"><i class="icon-github"></i></a>
<a href="https://opencollective.com/liquidjs" class="mobile-nav-link" rel="external" target="_blank"><i class="icon-opencollective"></i></a>
<div id="mobile-lang-select-wrap" class="mobile-nav-link">
<label for="mobile-lang-select"><i class="icon-network"></i></label>
<select id="mobile-lang-select" data-canonical="tutorials/sync-and-async.html">
<option value="en" selected>English</option>
<option value="zh-cn">简体中文</option>
</select>
</div>
</div>
</nav>
<script src="../js/main.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
document.getElementById('search-input-wrap').classList.add('on');
docsearch({
apiKey: '01f36cc168657a26a385308b9e721bc6',
indexName: 'liquidjs',
inputSelector: '#search-input',
debug: false
});
</script>
</body>
</html>