Theme Hooks - 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/BG9JQYMZAKGW/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/BG9JQYMZAKGW/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> <p>Themes can be imbued with the power of plugins via a special themehooks php file. Using the themehooks file, you can override existing functions in Vanilla, plug in to existing Vanilla events, and set data for your views.</p><h2 data-id="naming">Naming</h2><p>To use event hooks in a theme, the theme must have a plugin with a classname ending in <code class="code codeInline" spellcheck="false" tabindex="0">ThemeHooks</code> and must have a filename ending in <code class="code codeInline" spellcheck="false" tabindex="0">ThemeHooks.php</code>. The prevailing convention results in a class <code class="code codeInline" spellcheck="false" tabindex="0">MySiteThemeHooks</code> and file <code class="code codeInline" spellcheck="false" tabindex="0">MySiteThemeHooks.php</code>. This file must be located in the root of your addon.</p><h2 data-id="events">Events</h2><p>To get a better understanding of what the theme hooks are capable of, familiarize yourself with <a href="https://success.vanillaforums.com/kb/articles/245-event-and-handlers" rel="nofollow noreferrer ugc">custom events & handlers</a>, <a href="https://success.vanillaforums.com/kb/articles/245-event-and-handlers#magic-events" rel="nofollow noreferrer ugc">magic events</a>, <a href="https://success.vanillaforums.com/kb/articles/245-event-and-handlers#example-events" rel="nofollow noreferrer ugc">example events</a> and <a href="https://success.vanillaforums.com/kb/articles/245-event-and-handlers#magic-methods" rel="nofollow noreferrer ugc">magic methods</a>.</p><p>Here’s an example of a themehooks file that sets some config variables, adds locale data for the view, adds a respond button to the discussion page, and overrides a method to add an extra css class to a menu count span.</p><h2 data-id="example-themehooks">Example Themehooks</h2><pre class="code codeBlock" spellcheck="false" tabindex="0"><?php /** * @author My Name <name@email.com> * @copyright 2015 (c) My Organizations * @license http://opensource.org/licenses/MIT MIT */ /** * Adds locale data to the view, and adds a respond button to the discussion page. */ class MyThemeNameThemeHooks extends Gdn_Plugin { /** * Fetches the current locale and sets the data for the theme view. * Render the locale in a smarty template using {$locale} * * @param Controller $sender The sending controller object. */ public function base_render_before($sender) { // Bail out if we're in the dashboard if (inSection('Dashboard')) { return; } // Fetch the currently enabled locale (en by default) $locale = Gdn::locale()->current(); $sender->setData('locale', $locale); } /** * Adds a 'respond' button on a discussion page below the discussion title * that links to the comment form. * * @param DiscussionController $sender The sending object. */ public function discussionController_afterDiscussionTitle_handler($sender) { // Ensure the user is signed in. if (Gdn::session()) { echo '<div class="below-discussion-title">'. '<a class="respond-button Button" href="#Form_Comment">Respond</a>'. '</div>'; } } } </pre><h2 data-id="common-hooks">Common Hooks</h2><p>There are a few common functions for a themehooks file.</p><h3 data-id="base_render_before()">base_render_before()</h3><p>This runs on every single page load before the render. This includes the Dashboard so be sure to exclude it! This is also a good place to use the <code class="code codeInline" spellcheck="false" tabindex="0">Gdn_Controller</code> method <code class="code codeInline" spellcheck="false" tabindex="0">setData()</code> to inject data into your Smarty templates. For details on these controller methods, see our <a href="https://docs.vanillaforums.com/developer/framework/controllers/#setdata-and-data" rel="nofollow noreferrer ugc">framework documentation</a>.</p><p>For information about using this injected data see <a href="https://docs.vanillaforums.com/developer/smarty/#accessing-controller-data-with-smarty" rel="nofollow noreferrer ugc">Accessing Controller Data with Smarty</a>. If you’re trying to verify that the data that is getting passed into the template, try out the <a href="https://success.vanillaforums.com/kb/articles/235-smarty-functions#function%3A-debug_vars" rel="nofollow noreferrer ugc">{debug} function</a> in smarty.</p><h3 data-id="setup()">setup()</h3><p>This runs when when an addon is first enabled. This is a good place for setting configuration values your theme may rely on, but is not required. Sometimes it may be desirable to put most of this content inside the structure() method and call structure from the setup method. See the example below.</p><h3 data-id="structure()">structure()</h3><p>This update function is called every time you reach the <code class="code codeInline" spellcheck="false" tabindex="0">/utility/update</code> endpoint. Many plugins use this as a place to update the database, but it can be a good place for configuration values as well, and can be used to manually create a category, discussion, Pocket, etc that your theme relies on. See the example below.</p><p>This event is optional.</p><h3 data-id="example">Example</h3><p>Here is an example of setup method being used.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">public function setup() { saveToConfig([ 'Vanilla.Categories.Layout' => 'table', 'Vanilla.Discussions.Layout' => 'table', 'Garden.Thumbnail.Size' => '200', ]); Pocket::touch("My Custom Pocket", "<div>My custom pocket contents</div>"); } </pre><h2 data-id="other-examples">Other Examples</h2><p>For more examples see our <a href="https://success.vanillaforums.com/kb/articles/245-event-and-handlers#example-events" rel="nofollow noreferrer ugc">Example Events section</a>.</p> </article> </main>