Using a Twig Master View - HL Vanilla Community
<main> <article class="userContent"> <p>For most of Vanilla's existence, themes have been able to specify a "master view" or template for a site, generally located at <code class="code codeInline" spellcheck="false" tabindex="0">my-theme/views/default.master.tpl</code>. This was the full template that the page would get rendered in.</p><p>Today, Vanilla offers a newer, twig templating system for creating theme layouts. Rather than providing a single, total master view, it is possible to specify a Default Template for a theme.</p><h2 data-id="how-to-configure-a-default-template">How to configure a default template</h2><p>The first step to configuring a default template is enable a theme feature.</p><p><strong>my-theme/addon.json</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ // rest of addon.json "Features": { "SharedMasterView": true } } </pre><p>With this enabled in your <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code> file, your theme will begin using a shared master view, and start using a master template.</p><p>You can find <a href="https://github.com/vanilla/vanilla/blob/master/library/Vanilla/Web/MasterView.twig" rel="nofollow noreferrer ugc">the core master view here</a>. It <strong>cannot</strong> be overridden.</p><p>The <a href="https://github.com/vanilla/vanilla/blob/master/addons/themes/theme-foundation/views/layout.default.twig" rel="nofollow noreferrer ugc">default layout template can be found here</a>. It <strong>can</strong> be overridden.</p><h2 data-id="overriding-the-default-layout">Overriding the default layout</h2><p>A custom theme can override the default layout template with a custom one. To do this, create a new file in your theme.</p><p><strong>my-theme/views/layout.default.twig</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Copy the default template here </pre><p>From here you can add custom HTML structures into your page, use conditionals to conditionally render things, and make use of any of the data injected into the page.</p><h2 data-id="default-template-available-functions">Default Template Available Functions</h2><p>All common twig functions are available in master templates.</p><div class="js-embed embedResponsive" data-embedjson="{"body":"Built In Twig Functions Twig comes with some built-in functions and filters that can be useful when creating view templates. The most common include: Default Values The |default and |default(\"Default Value\") filters apply some default value when used with a null value. A common use case is safely accessing some variable…","photoUrl":"https:\/\/us.v-cdn.net\/6030677\/uploads\/947\/TM5DAO1BWY5V.png","url":"https:\/\/success.vanillaforums.com\/kb\/articles\/265-common-twig-functions","embedType":"link","name":"Common Twig Functions - Vanilla Success"}"> <a href="https://success.vanillaforums.com/kb/articles/265-common-twig-functions" rel="nofollow noreferrer ugc"> https://success.vanillaforums.com/kb/articles/265-common-twig-functions </a> </div><p>The following additional functions are also available</p><h3 data-id="rendercontrollerasset(string-%24assetname)">renderControllerAsset(string $assetName)</h3><p>Render an asset from the controller. The 2 important assets are <code class="code codeInline" spellcheck="false" tabindex="0">Content</code> and <code class="code codeInline" spellcheck="false" tabindex="0">Panel</code>.</p><h4 data-id="usage">Usage</h4><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ renderControllerAsset('Content') }} </pre><h3 data-id="rendermodule(string-%24modulename-array-%24moduleargs)">renderModule(string $moduleName, array $moduleArgs)</h3><p>Render a <code class="code codeInline" spellcheck="false" tabindex="0">Gdn_Module</code>. See <a href="https://success.vanillaforums.com/kb/articles/253-gdn-module" rel="nofollow noreferrer ugc">the </a><a href="https://success.vanillaforums.com/kb/articles/253-gdn-module" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">Gdn_Module</code></a><a href="https://success.vanillaforums.com/kb/articles/253-gdn-module" rel="nofollow noreferrer ugc"> documentation</a>.</p><h4 data-id="parameters">Parameters</h4><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">$moduleName</code> - The name of the module to render. </li><li><code class="code codeInline" spellcheck="false" tabindex="0">$moduleArgs</code> - Argument for creating the module. These get mapped to public properties on the module.</li></ul><h4 data-id="example-1">Example 1</h4><p>Create a module showing other discussions in the same category as the current one.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{% if inSection("Discussion") %} {{ renderModule( "DiscussionsModule", {showPhotos: true, limit: 3, categoryIDs: [Category.CategoryID]} ) }} {% endif %} </pre><h4 data-id="example-2">Example 2</h4><p>Create a weekly leaderboards module.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ renderModule("LeaderBoardModule", { SlotType: 'w', Limit: 3} ) }} </pre><h3 data-id="renderbreadcrumbs(array-%24options)">renderBreadcrumbs(array $options)</h3><p>Render the current pages breadcrumbs.</p><h4 data-id="parameters-1">Parameters</h4><p>This function takes an arguments array. At the time of writing there are 2 arguments.</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">HomeUrl</code> - The URL to use on the top level "Home" breadcrumb.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">HideLast</code> - Hide the last breadcrumb.</li></ul><h4 data-id="usage-1">Usage</h4><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ renderBreadcrumbs({ HomeUrl: 'https://my-main-site.com', HideLast: true }) }} </pre><h3 data-id="renderpocket(string-%24pocketname)">renderPocket(string $pocketName)</h3><p>Used to render a custom pocket location. If the pocket can't be found, nothing will render.</p><h4 data-id="usage-2">Usage</h4><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ renderPocket('My Custom Pocket') }} </pre><h3 data-id="renderbanner(array-%24arguments)">renderBanner(array $arguments)</h3><p>Render a banner on the page. <em>Note: For the banner to appear on content pages (eg. discussion/comments, search), you must enable the the content banner in the theme.</em></p><h4 data-id="parameters-2">Parameters</h4><p>All of these parameters have contextual default values.</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">title</code> - The title to display in the banner. Defaults to current category name, or theme title, or site title in that order..</li><li><code class="code codeInline" spellcheck="false" tabindex="0">description</code> - The description to display in the banner. Defaults to category description, or contextual description set on the controller.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">backgroundImage</code> - The URL to background image of the banner. See <a href="https://success.vanillaforums.com/kb/articles/16-community-banner-image" rel="nofollow noreferrer ugc">the Banner Image documentation</a>.</li></ul><h4 data-id="usage-3">Usage</h4><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ renderBanner() }} // With arguments {{ renderBanner({ title: "Always use this title" }) }} </pre><h2 data-id="available-data-in-the-template">Available Data in the Template</h2><p>Any data used to render the controller will be passed into the template. This includes:</p><ul><li>Current Category when available</li><li>Current Subcommunity when available</li><li>Current locale</li><li>Everything from <code class="code codeInline" spellcheck="false" tabindex="0">SiteMeta</code> - <a href="https://github.com/vanilla/vanilla/blob/5748851ddfb738b3331b1afcfe2c901bd2789cc6/library/Vanilla/Models/SiteMeta.php#L203-L242" rel="nofollow noreferrer ugc">See the code</a></li><li>Current discussion when available</li><li>Current User</li></ul><p>To see all of the data in the current template, enable the <code class="code codeInline" spellcheck="false" tabindex="0">Debug</code> config, and temporarily add this to your template.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ dump() }} </pre><p>You can make this more specific by specifying some particular piece of data to dump. Eg.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{{ dump('Category') }} </pre><p><br></p> </article> </main>