Labyricorn/liquidjs
1
0
Fork 0
mirror of https://github.com/harttle/liquidjs.git synced 2026-09-17 05:10:40 -07:00
Code Issues Packages Projects Releases Wiki Activity

Deploying to gh-pages from @ harttle/liquidjs@8db6c7b28d 🚀

Browse Source
This commit is contained in:
harttle
2022-01-23 06:26:25 +00:00
parent 5a775713f7
commit 8774d5f6f1
550 changed files with 4711 additions and 2885 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tutorials/render-file.html
+44 -8
View File
@@ -77,7 +77,7 @@
<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 current">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="sync-and-async.html" class="sidebar-link">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>
<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 current">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">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">
@@ -93,17 +93,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/liquid_options_.liquidoptions.html#Optional-root">template root</a> and call <a href="../api/classes/liquid_.liquid.html#renderFile">renderFile</a> or <a href="../api/classes/liquid_.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="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&#x2F;
├── 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="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> Liquid(&#123;</span><br><span class="line"> <span class="attr">root</span>: path.resolve(__dirname, <span class="string">&#x27;views/&#x27;</span>), <span class="comment">// root for layouts/includes lookup</span></span><br><span class="line"> <span class="attr">extname</span>: <span class="string">&#x27;.liquid&#x27;</span> <span class="comment">// used for layouts/includes, defaults &quot;&quot;</span></span><br><span class="line">&#125;);</span><br><span class="line">engine</span><br><span class="line"> .renderFile(<span class="string">&quot;hello&quot;</span>, &#123;<span class="attr">name</span>: <span class="string">&#x27;alice&#x27;</span>&#125;) <span class="comment">// will read and render `views/hello.liquid`</span></span><br><span class="line"> .then(<span class="built_in">console</span>.log) <span class="comment">// outputs &quot;Alice&quot;</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">&#123;</span>
root<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>
extname<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">&#125;</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">&#123;</span>name<span class="token operator">:</span> <span class="token string">'alice'</span><span class="token punctuation">&#125;</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="code"><pre><span class="line">&gt; 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">&gt; 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_.liquid.html#renderFile">renderFile</a>, <a href="../api/classes/liquid_.liquid.html#parseFile">parseFile</a>, <a href="../api/classes/liquid_.liquid.html#renderFilesync">renderFileSync</a>, <a href="../api/classes/liquid_.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/liquid_options_.liquidoptions.html#Optional-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="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> Liquid(&#123;</span><br><span class="line"> <span class="attr">root</span>: [<span class="string">&#x27;views/&#x27;</span>, <span class="string">&#x27;views/partials/&#x27;</span>],</span><br><span class="line"> <span class="attr">extname</span>: <span class="string">&#x27;.liquid&#x27;</span></span><br><span class="line">&#125;);</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">&#123;</span>
root<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>
extname<span class="token operator">:</span> <span class="token string">'.liquid'</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></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>
@@ -121,7 +135,29 @@
<p>If fetch fails, a 404/500 error or network failures for example, an <code>ENOENT</code> error will be throwed.<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 abstract file system interface in <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/ifs.ts">src/fs/ifs.ts</a> and the default implementation is <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/node.ts">src/fs/node.ts</a> for Node.js and <a target="_blank" rel="noopener external nofollow noreferrer" href="https://github.com/harttle/liquidjs/blob/master/src/fs/browser.ts">src/fs/browser.ts</a> for the browser bundle.</p>
<p>The <code>Liquid</code> constructor provides a <a href="../api/interfaces/liquid_options_.liquidoptions.html#Optional-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="code"><pre><span class="line"><span class="keyword">var</span> engine = <span class="keyword">new</span> Liquid(&#123;</span><br><span class="line"> <span class="attr">fs</span>: &#123;</span><br><span class="line"> readFileSync (file) &#123;</span><br><span class="line"> <span class="keyword">return</span> db.model(<span class="string">&#x27;Template&#x27;</span>).findByIdSync(file).text</span><br><span class="line"> &#125;,</span><br><span class="line"> <span class="keyword">async</span> readFile (file) &#123;</span><br><span class="line"> <span class="keyword">const</span> template = <span class="keyword">await</span> db.model(<span class="string">&#x27;Template&#x27;</span>).findById(file)</span><br><span class="line"> <span class="keyword">return</span> template.text</span><br><span class="line"> &#125;,</span><br><span class="line"> existsSync () &#123;</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> &#125;,</span><br><span class="line"> exists () &#123;</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> &#125;,</span><br><span class="line"> contains () &#123;</span><br><span class="line"> <span class="keyword">return</span> <span class="literal">true</span></span><br><span class="line"> &#125;,</span><br><span class="line"> <span class="function"><span class="title">resolve</span>(<span class="params">root, file, ext</span>)</span> &#123;</span><br><span class="line"> <span class="keyword">return</span> file</span><br><span class="line"> &#125;</span><br><span class="line"> &#125;</span><br><span class="line">&#125;);</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">&#123;</span>
fs<span class="token operator">:</span> <span class="token punctuation">&#123;</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">&#123;</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">&#125;</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">&#123;</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">&#125;</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">&#123;</span>
<span class="token keyword">return</span> <span class="token boolean">true</span>
<span class="token punctuation">&#125;</span><span class="token punctuation">,</span>
<span class="token function">exists</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">&#123;</span>
<span class="token keyword">return</span> <span class="token boolean">true</span>
<span class="token punctuation">&#125;</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">&#123;</span>
<span class="token keyword">return</span> <span class="token boolean">true</span>
<span class="token punctuation">&#125;</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">&#123;</span>
<span class="token keyword">return</span> file
<span class="token punctuation">&#125;</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></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>
@@ -129,7 +165,7 @@
</div>
<footer class="article-footer">
<time class="article-footer-updated" datetime="2022-01-22T16:03:03.364Z" itemprop="dateModified">Last updated: 2022-01-22</time>
<time class="article-footer-updated" datetime="2022-01-23T06:25:32.646Z" itemprop="dateModified">Last updated: 2022-01-23</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>
@@ -176,7 +212,7 @@
</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 current">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="sync-and-async.html" class="mobile-nav-link">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>
<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 current">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">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>