Using a Smarty Master View - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/VIUVTL7HH3NI/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/VIUVTL7HH3NI/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="smarty-master-view">Smarty Master View</h2><p>This master view acts as the wrapper for each page in your theme. Often, this is the only view you'll have to manipulate. The master view file is called the <code class="code codeInline" spellcheck="false" tabindex="0">default.master.tpl</code> (Smarty template) or the <code class="code codeInline" spellcheck="false" tabindex="0">default.master.php</code>. We recommend using Smarty templates for your master view, however you can decide to use a regular ol' php view if you like.</p><p>To override the default master view:</p><ol><li>Create a new file called <code class="code codeInline" spellcheck="false" tabindex="0">default.master.tpl</code> (or default.master.php)</li><li>Place it in the views folder in your theme folder (i.e., <code class="code codeInline" spellcheck="false" tabindex="0">/themes/{your_theme_name}/views/</code>)</li></ol><p>If you're new to this, it's probably a good idea to copy the content of <code class="code codeInline" spellcheck="false" tabindex="0">/applications/dashboard/views/default.master.tpl</code> into your theme's master view and manipulate it from there.</p><h3 data-id="smarty-tags-in-the-master-view">Smarty tags in the master view</h3><p>You can accomplish a great deal of things using Smarty in your default master view. We highly recommend checking out our <a href="https://success.vanillaforums.com/kb/articles/233-smarty-overview" rel="nofollow noreferrer ugc">complete Smarty docs</a> to get a bearing on this, but here's what you need to know to get started.</p><h3 data-id="required-tags">Required tags</h3><p>There are a few assets that need to appear and an event that needs to be fired from your master view in order for everything to run smoothly. The contents of these tags are programmatically generated, depending on your forum's data and configuration. Omitting any one of these tags may result in some strange behaviour on your forum.</p><ol><li><strong>The head asset</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{asset name="Head"}</code> This should appear within the head <code class="code codeInline" spellcheck="false" tabindex="0"><head></code> block of your html. It contains the css and javascript needed for your applications and plugins.</li><li><strong>The content asset</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{asset name="Content"}</code> This should appear within the body <code class="code codeInline" spellcheck="false" tabindex="0"><body></code> block of your html. It contains the main content of any page.</li><li><strong>The panel asset</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{asset name="Panel"}</code> This should appear within the body <code class="code codeInline" spellcheck="false" tabindex="0"><body></code> block of your html. It generally adds tertiary functionality to the forum, however it does include necessary functionality for the <em>Profile</em> and <em>Conversation</em> sections of forum. If you decide to go with a panel-less design, we recommend using css to hide the panel on pages where it's unnecessary or to manually adding the panel into the forum sections where it is necessary using the inSection function (see the <em>More Smarty tips and tricks</em> section below for an example of this).</li><li><strong>The foot asset</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{asset name="Foot"}</code> This should appear after the Content asset within the body <code class="code codeInline" spellcheck="false" tabindex="0"><body></code> block of your html. Plugins and applications add content or scripts to this asset.</li><li><strong>The AfterBody event</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{event name="AfterBody"}</code> This should appear just before the closing body tag <code class="code codeInline" spellcheck="false" tabindex="0"></body></code> of your html. Plugins and applications hook into this event to generate content.</li></ol><h3 data-id="useful-tags-and-practices">Useful tags and practices</h3><ol><li><strong>Searchbox</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{searchbox}</code> Adds a handy little searchbox.</li><li><strong>Breadcrumbs</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{breadcrumbs}</code> Adds breadcrumbs, a crucial detail when navigating a forum.</li><li><strong>The Me module</strong> <code class="code codeInline" spellcheck="false" tabindex="0">{module name="MeModule"}</code> Adds the Me module. This module contains dropdowns for notifications, bookmarks, conversations and settings. It helps a logged-in user access what's important to them.</li><li><strong>Opening body tag</strong> <code class="code codeInline" spellcheck="false" tabindex="0"><body id="{$BodyID}" class="{$BodyClass}"></code> This is how we recommend opening your body element. It adds programmatically generated CSS classes and ids to the body block, which are very useful for targeting sections when styling your forum.</li></ol><p>The most up-to-date set of Smarty functions and modifiers can be tracked down in <code class="code codeInline" spellcheck="false" tabindex="0">/library/SmartyPlugins</code>.</p><h3 data-id="more-smarty-tips-and-tricks">More Smarty tips and tricks</h3><ol><li><strong>Signed in users</strong> You can add content to your forum depending on whether a user is signed in or not. For example: <code class="code codeInline" spellcheck="false" tabindex="0">{if $User.SignedIn}Welcome back!{/if}</code> This snippet adds a welcome message for any signed in user.</li><li><strong>Forum sections</strong> You can add content to your forum depending on what section you're in. For example: <code class="code codeInline" spellcheck="false" tabindex="0">{if inSection(['Profile', 'Conversation'])}{asset name="Panel"}{/if}</code> This snippet adds the panel asset to the Profile and Conversation sections of the forum. You can find the section name of any page in the forum by using your browser's web tools to inspect the body element. One of the CSS classes on the body element will be Section-*, where * is the section name. (Assuming you have adhered to the opening body tag tip above.)</li></ol><h3 data-id="smarty-variables-and-setting-page-data-(advanced)">Smarty variables and setting page data (Advanced)</h3><p>If you've read this far, you may have noticed we've used some variables above to determine the logged-in state of the user (<code class="code codeInline" spellcheck="false" tabindex="0">$User</code>) and to add body classes to and ids to the body tag (<code class="code codeInline" spellcheck="false" tabindex="0">$BodyID</code> and <code class="code codeInline" spellcheck="false" tabindex="0">$BodyClass</code>). You'll probably not be surprised to learn that there are even more variables you can access and use!</p><p><strong>For use in testing environments only</strong>, to view all the variables you have access to, you can include a special tag anywhere in your default master view: <code class="code codeInline" spellcheck="false" tabindex="0">{debug_vars}</code> After adding this tag, refresh your forum page in a browser. A popup will show all the data variables available for use on the given page (you gotta make sure your browser's allowing popups here).</p><p>To go even further, you can use <a href="unsafe:/developer/addons/events-and-handlers" rel="nofollow noreferrer ugc">event handlers</a> to assign data to variables that you can then use in your view.</p><h2 data-id="smarty-default-master-view-example">Smarty default master view example</h2><p>To see how it all fits together you can check Keystone (one of our core themes) <a href="https://github.com/vanilla/vanilla/blob/master/addons/themes/keystone/views/default.master.tpl" rel="nofollow noreferrer ugc">master view</a>.</p> </article> </main>