Every Vanilla addons must declare certain information about itself. This includes:
- Addon Metadata
- Author Metadata
- Addon support links
- Addon configuration details
- Details about how to load the addon
The addon.json file
In an effort to simplify the management and creation of plugins, applications, and themes, Vanilla 2.5 and onwards uses a single unified addon information format. The new format is a json file that should live in the root of your addon’s directory. It looks like this:
addon.json example
{
"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"
]
}
Theme addon.json example
Theme’s tend to be a little bit simpler and would look like this:
{
"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
},
}
Meta Information
key
The theme key. This should be unique and must exactly match the folder name, including capitalization. So an addon with the key example-addon would need to be located in a plugins/example-addon directory in your Vanilla installation. Addon keys and their directories should be named in dashed-lower-case.
name
The name of your addon. This will appear in the dashboard. Defaults to the key.
To include special characters here or in the description, use their HTML entity code.
"name": "Adam's Fancy Addon"
description
A short description of your addon. This will also appear in the dashboard.
To include special characters here or in the description, use their HTML entity code.
"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."
icon
The location of the your icon file relative to the addon’s folder.
"icon": "my-addon-icon.jpg",
version
Version of the addon. You should increment this every time you ship a new version of your addon. Try to familiarize yourself with semantic versioning.
"version": "1.0.6",
authors
An array of authors of an addon.
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com",
"homepage": "http://yourdomain.com"
}
],
license
License that you wish to distribute your addon under.
"license": "MIT",
Types & Priority
type
Can be either addon, theme, or locale.
"type": "theme",
priority
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.
The following defaults are set:
- Application:
10 - Locale:
11 - Plugin:
100 - Theme:
1000
"priority": "99",
require
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.
"require": {
"vanilla": ">=2.4",
"someOtherPlugin": ">=1.4.1"
},
Documentation & Settings
documentationUrl
A link to documentation of your addon. It will show as an icon next to the addon name in the dashboard.
"documentationUrl": "http://mysite.com/myplugindocumentation.html",
settingsUrl
Link to an in-dashboard settings page. This will be loaded in a popup over the addon manager.
"settingsUrl": "/settings/mysettingspage",
settingsPermission
The permission required to access the addon’s settings page.
"settingsPermission": "Garden.Settings.Manage",
Permissions
registerPermissions
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.
"registerPermissions": {
"FancyAddon.NewPostType.Add": "Garden.Discussions.Add",
"FancyAddon.Stuff.Manage": "Garden.Settings.Manage"
},
Theme Only
isResponsive
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 false for backwards compatibility reasons, it is highly recommended to make responsive themes.
"isResponsive": true,
layout
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.
See the user facing documentation about layouts.
Layouts for Discussions
Layouts for categories
"layout": {
"categories": "modern",
"discussions": "modern"
},
Cloud Only
Sites
A list of Vanilla Forums Cloud sites to show display the addon on. See Addon Visibility for details.
"sites": [
"mysite.vanillastaging.com",
"mysite.vanillacommunities.com
],