Before proceeding with this guide, you'll want a local installation. Follow our Localhost Configuration guide to install Vanilla on your development machine.
Quickstart links
Quickstart guide
Higher Logic Vanilla (Vanilla) is built on an object-oriented, model-view-controller (MVC) framework. If you’re coming from a mostly function-based world like WordPress or Drupal, this might read like a foreign language. If so, that's okay. Ask questions in our community after you follow this guide and play with the examples.
1. Name your Addon
Vanilla generally uses simple names for our addons; we favor descriptive names over clever ones or mini-brands.
Your addon needs a user-facing name, and a ‘slug’ name without spaces or special characters. If your addon is named “Lincoln’s Fancy Addon,” a good slug name would be lincolns-fancy-addon or even just fancyaddon.
2. Define your Addon
- Create a folder in the
plugins directory, using the slug name you chose (e.g., fancyaddon). - Create a file called
addon.json. This file will define basic information about your addon. View all of the options. - Open the file and add the addon information. You can use this as a starting point:
{
"type": "addon",
"key": "fancyaddon",
"name": "Lincoln’s Fancy Addon",
"description": "This is a fancy addon!",
"version": "1.0.0",
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com",
"homepage": "http://yourdomain.com"
}
]
}
🛑 IMPORTANT: The key value (fancyaddon above) must exactly match the folder name, including capitalization. Some systems are case-insensitive and will ignore differences in capitalization, but others are not, so make sure they match.
Define basic info
- The
name parameter is optional; it will default to the slug if omitted. To include special characters here or in the description, use their HTML entity code. - Provide a
description that briefly explains what your addon does from the users’ perspective. For version, familiarize yourself with semantic versioning. - The
authors parameters are at your discretion. We recommend using a support address for both the email and URL. authors takes an array so be sure to include anyone who’s name you want on the addon. - All further optional parameters described below default to
false if not defined.
Define a settings page
To create a “Settings” button that will appear on the addon after it's enabled, add these to your definition:
"settingsUrl": "/settings/somepagehere",
"settingsPermission": "Garden.Settings.Manage",
Define requirements
You can require a certain version of Vanilla before your addon can be enabled. To do so, add this:
"require": {
"vanilla": ">=3.0"
},
You can require other addons to be enabled be using this instead:
"require": {
"vanilla": ">=3.0",
"Akismet": ">=1.0.1",
"StopForumSpam": ">=1.0"
},
These checks only apply to addons being enabled/disabled in the Dashboard. If a user manually enables your addon or disables a dependency in the configuration, these checks may not apply. Therefore, it's very important to use defensive programming techniques to guard against missing prerequisites, rather than simply assuming they will always be there just because you put it in the requirements.
Visibility
If you have Vanilla Cloud, make sure to also set your addon’s visibility.
Define new permissions
Adding new permissions via addon is easy. Any permission defined here will be added as soon as the addon is enabled. It’s important to know more about using permissions in Vanilla before doing this.
You can provide an array of permission names using dot syntax. You can optionally use key/value pairs to set a default (1 will give all roles the permission; 0 is the default and leaves it off for all roles to start).
"registerPermissions": {
"FancyAddon.Stuff.Add" => 1
},
Or set the default to whether or not the role currently has an existing permission:
"registerPermissions": {
"FancyAddon.Stuff.Add": "Garden.Settings.Manage"
},
This allows you to set good defaults while allowing them to be changed independently in the future.
Adding JavaScript or CSS
