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
Vanilla is built on an object-oriented, MVC framework. If you’re coming at this from a mostly function-based world like WordPress or Drupal, this might read like moonspeak. That’s OK! Soak it up and ask questions on the forum after you follow this guide and play with the examples.
Ready to code? Hang onto your butts, here we go:
1. Name your Addon
Conventionally, Vanilla uses, well, pretty vanilla addon names. We often 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
First, create a folder in the plugins directory, using the slug name you selected (e.g. fancyaddon). Next let’s create a file called addon.json. This file will define basic information about our addon. See an exhaustive list of all of the options. Next open the file add the addon information. You can use this as a starting point:
{
"type": "addon",
"key": "fancyaddon",
"name": "Adam'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"
}
]
}
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 great 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 is 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. Require a certain version of Vanilla by adding 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 addon’s being enabled/disabled in the dashboard. If a user manually enables your addon or disables a dependancy in the configuration these checks may not apply. Therefore, it is 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’ve got 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.
Whew!
That whole definitions section probably didn’t seem very quick, but you just did a huge amount of work in just a few lines of code.
Addon some Javascript or CSS