For most of Vanilla's existence, themes have been able to specify a "master view" or template for a site, generally located at my-theme/views/default.master.tpl. This was the full template that the page would get rendered in.
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.
How to configure a default template
The first step to configuring a default template is enable a theme feature.
my-theme/addon.json
{
// rest of addon.json
"Features": {
"SharedMasterView": true
}
}
With this enabled in your addon.json file, your theme will begin using a shared master view, and start using a master template.
You can find the core master view here. It cannot be overridden.
The default layout template can be found here. It can be overridden.
Overriding the default layout
A custom theme can override the default layout template with a custom one. To do this, create a new file in your theme.
my-theme/views/layout.default.twig
// Copy the default template here
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.
Default Template Available Functions
All common twig functions are available in master templates.
The following additional functions are also available
renderControllerAsset(string $assetName)
Render an asset from the controller. The 2 important assets are Content and Panel.
Usage
{{ renderControllerAsset('Content') }}
renderModule(string $moduleName, array $moduleArgs)
Render a Gdn_Module. See the Gdn_Module documentation.
Parameters
$moduleName - The name of the module to render. $moduleArgs - Argument for creating the module. These get mapped to public properties on the module.
Example 1
Create a module showing other discussions in the same category as the current one.
{% if inSection("Discussion") %}
{{ renderModule(
"DiscussionsModule",
{showPhotos: true, limit: 3, categoryIDs: [Category.CategoryID]}
) }}
{% endif %}
Example 2
Create a weekly leaderboards module.
{{ renderModule("LeaderBoardModule", { SlotType: 'w', Limit: 3} ) }}
renderBreadcrumbs(array $options)
Render the current pages breadcrumbs.
Parameters
This function takes an arguments array. At the time of writing there are 2 arguments.
HomeUrl - The URL to use on the top level "Home" breadcrumb.HideLast - Hide the last breadcrumb.
Usage
{{ renderBreadcrumbs({ HomeUrl: 'https://my-main-site.com', HideLast: true }) }}
renderPocket(string $pocketName)
Used to render a custom pocket location. If the pocket can't be found, nothing will render.
Usage
{{ renderPocket('My Custom Pocket') }}
renderBanner(array $arguments)
Render a banner on the page. Note: For the banner to appear on content pages (eg. discussion/comments, search), you must enable the the content banner in the theme.
Parameters
All of these parameters have contextual default values.
title - The title to display in the banner. Defaults to current category name, or theme title, or site title in that order..description - The description to display in the banner. Defaults to category description, or contextual description set on the controller.backgroundImage - The URL to background image of the banner. See the Banner Image documentation.
Usage
{{ renderBanner() }}
// With arguments
{{ renderBanner({ title: "Always use this title" }) }}
Available Data in the Template
Any data used to render the controller will be passed into the template. This includes:
- Current Category when available
- Current Subcommunity when available
- Current locale
- Everything from
SiteMeta - See the code - Current discussion when available
- Current User
To see all of the data in the current template, enable the Debug config, and temporarily add this to your template.
{{ dump() }}
You can make this more specific by specifying some particular piece of data to dump. Eg.
{{ dump('Category') }}