The addon.json File - Vanilla Success
<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/8E1SAMNMXIXZ/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/8E1SAMNMXIXZ/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>Every Vanilla addons must declare certain information about itself. This includes:</p><ul><li>Addon Metadata</li><li>Author Metadata</li><li>Addon support links</li><li>Addon configuration details</li><li>Details about how to load the addon</li></ul><h2 data-id="the-addon.json-file">The <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code> file</h2><p>In an effort to simplify the management and creation of plugins, applications, and themes, Vanilla <code class="code codeInline" spellcheck="false" tabindex="0">2.5</code> and onwards uses a single unified addon information format. The new format is a <code class="code codeInline" spellcheck="false" tabindex="0">json</code> file that should live in the root of your addon’s directory. It looks like this:</p><h3 data-id="addon.json-example"><code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code> example</h3><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "key": "example-addon", "name": "Example Addon", "description": "Provides an example of an Addon", "version": "2.0.0", "documentationUrl": "http://site.com/link-to-documentation", "type": "addon", "icon": "icon-location.png", "mobileFriendly": true, "hasLocale": false, "settingsUrl": "/settings/myaddon", "settingsPermission": "Garden.Settings.Manage", "registerPermissions": { "Plugins.MyPlugin.MyPermission": "Garden.Settings.Manage" }, "authors": [ { "name": "Todd Burry", "email": "todd@vanillaforums.com", "homepage": "https://open.vanillaforums.com/profile/todd" } ], "require": { "vanilla": ">=2.4" }, "sites": [ "mysite.vanillastaging.com", "mysite.vanillacommunities.com" ] } </pre><h3 data-id="theme-addon.json-example">Theme <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code> example</h3><p>Theme’s tend to be a little bit simpler and would look like this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "key": "example-theme", "name": "Example Theme", "description": "Custom Theme Example", "version": "2.0.0", "type": "theme", "license": "MIT", "author": [ { "name": "Adam Charron", "email": "adam.c@vanillaforums.com" } ], "layout": { "categories": "modern", "discussions": "modern" }, "sites": [ "mysite.vanillastaging.com", "mysite.vanillacommunities.com" ], "isResponsive": true, "Features": { "ProfileHeader": true, "SharedMasterView": true, "NewFlyouts": true, "DataDrivenForumColors": true }, } </pre><h2 data-id="meta-information">Meta Information</h2><h3 data-id="key">key</h3><p>The theme key. This should be unique and <strong><em>must exactly match</em></strong> the folder name, including capitalization. So an addon with the key <code class="code codeInline" spellcheck="false" tabindex="0">example-addon</code> would need to be located in a <code class="code codeInline" spellcheck="false" tabindex="0">plugins/example-addon</code> directory in your Vanilla installation. Addon keys and their directories should be named in <code class="code codeInline" spellcheck="false" tabindex="0">dashed-lower-case</code>.</p><h3 data-id="name">name</h3><p>The name of your addon. This will appear in the dashboard. Defaults to the <code class="code codeInline" spellcheck="false" tabindex="0">key</code>.</p><p><em>To include special characters here or in the description, use their </em><a href="https://www.w3schools.com/html/html_entities.asp" rel="nofollow noreferrer ugc"><em>HTML entity code</em></a><em>.</em></p><pre class="code codeBlock" spellcheck="false" tabindex="0">"name": "Adam's Fancy Addon" </pre><h3 data-id="description">description</h3><p>A short description of your addon. This will also appear in the dashboard.</p><p><em>To include special characters here or in the description, use their </em><a href="https://www.w3schools.com/html/html_entities.asp" rel="nofollow noreferrer ugc"><em>HTML entity code</em></a><em>.</em></p><pre class="code codeBlock" spellcheck="false" tabindex="0">"description": "An addon to add some specific functionality to a forum. It's made to support some use case affects x, y, and z parts of the forum." </pre><h3 data-id="icon">icon</h3><p>The location of the your icon file relative to the addon’s folder.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"icon": "my-addon-icon.jpg", </pre><h3 data-id="version">version</h3><p>Version of the addon. You should increment this every time you ship a new version of your addon. Try to familiarize yourself with <a href="http://semver.org/" rel="nofollow noreferrer ugc">semantic versioning</a>.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"version": "1.0.6", </pre><h3 data-id="authors">authors</h3><p>An array of authors of an addon.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"authors": [ { "name": "Your Name", "email": "you@yourdomain.com", "homepage": "http://yourdomain.com" } ], </pre><h3 data-id="license">license</h3><p>License that you wish to distribute your addon under.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"license": "MIT", </pre><h2 data-id="types-priority">Types & Priority</h2><h3 data-id="type">type</h3><p>Can be either <code class="code codeInline" spellcheck="false" tabindex="0">addon</code>, <code class="code codeInline" spellcheck="false" tabindex="0">theme</code>, or <code class="code codeInline" spellcheck="false" tabindex="0">locale</code>.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"type": "theme", </pre><h3 data-id="priority">priority</h3><p>Addons use a priority system to determine which order they load in. The higher the priority an addon has, the later in the process it loads. Avoid using this if you can.</p><p>The following defaults are set:</p><ul><li><strong>Application</strong>: <code class="code codeInline" spellcheck="false" tabindex="0">10</code></li><li><strong>Locale</strong>: <code class="code codeInline" spellcheck="false" tabindex="0">11</code></li><li><strong>Plugin</strong>: <code class="code codeInline" spellcheck="false" tabindex="0">100</code></li><li><strong>Theme</strong>: <code class="code codeInline" spellcheck="false" tabindex="0">1000</code></li></ul><pre class="code codeBlock" spellcheck="false" tabindex="0">"priority": "99", </pre><h3 data-id="require">require</h3><p>A map of dependancies and their minimum version. The addon manager ensure these addons (or vanilla version) will be active to enable your addon. If they are not found, the addon will not be able to be turned on.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"require": { "vanilla": ">=2.4", "someOtherPlugin": ">=1.4.1" }, </pre><h2 data-id="documentation-settings">Documentation & Settings</h2><h3 data-id="documentationurl">documentationUrl</h3><p>A link to documentation of your addon. It will show as an icon next to the addon name in the dashboard.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"documentationUrl": "http://mysite.com/myplugindocumentation.html", </pre><h3 data-id="settingsurl">settingsUrl</h3><p>Link to an in-dashboard settings page. This will be loaded in a popup over the addon manager.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"settingsUrl": "/settings/mysettingspage", </pre><h3 data-id="settingspermission">settingsPermission</h3><p>The permission required to access the addon’s settings page.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"settingsPermission": "Garden.Settings.Manage", </pre><h2 data-id="permissions">Permissions</h2><h3 data-id="registerpermissions">registerPermissions</h3><p>A map of new permissions created by the addon, and the default value of that permission. If the user has the permission on the right side, they will have the permission on the left side by default.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"registerPermissions": { "FancyAddon.NewPostType.Add": "Garden.Discussions.Add", "FancyAddon.Stuff.Manage": "Garden.Settings.Manage" }, </pre><h2 data-id="theme-only">Theme Only</h2><h3 data-id="isresponsive">isResponsive</h3><p>Setting this property tells the addon manager that your theme should be applied to both Mobile & Desktop sites at the same time. While this defaults to <code class="code codeInline" spellcheck="false" tabindex="0">false</code> for backwards compatibility reasons, it is highly recommended to make responsive themes.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"isResponsive": true, </pre><h3 data-id="layout">layout</h3><p>A theme only property that tells Vanilla which views the theme users. Sometimes custom themes only work with a specific view. Keep in mind that this will not block an admin from changing the views, but it will give them a warning in the dashboard.</p><p><em>See the </em><a href="https://success.vanillaforums.com/kb/articles/4-customizing-your-forums-appearance#homepage" rel="nofollow noreferrer ugc"><em>user facing documentation about layouts.</em></a></p><h4 data-id="layouts-for-discussions">Layouts for Discussions</h4><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">modern</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">table</code></li></ul><h4 data-id="layouts-for-categories">Layouts for categories</h4><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">modern</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">table</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">mixed</code></li></ul><pre class="code codeBlock" spellcheck="false" tabindex="0">"layout": { "categories": "modern", "discussions": "modern" }, </pre><h2 data-id="cloud-only">Cloud Only</h2><h3 data-id="sites">Sites</h3><p>A list of Vanilla Forums Cloud sites to show display the addon on. See <a href="https://docs.vanillaforums.com/developer/addons/addon-visibility" rel="nofollow noreferrer ugc">Addon Visibility</a> for details.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"sites": [ "mysite.vanillastaging.com", "mysite.vanillacommunities.com ], </pre> </article> </main>