Addon Quickstart Guide - HL Vanilla Community
<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/YFSPZ0JALXSD/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/YFSPZ0JALXSD/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> <div class="blockquote"><div class="blockquote-content"><p class="blockquote-line"><em>Before proceeding with this guide, you'll want a local installation. Follow our </em><a href="https://success.vanillaforums.com/kb/articles/155-localhost-configuration#installing-dependencies-building" rel="nofollow noreferrer ugc"><em>Localhost Configuration guide</em></a><em> to install Vanilla on your development machine.</em></p></div></div><h2 data-id="quickstart-links">Quickstart links</h2><ul><li><a href="https://success.vanillaforums.com/kb/articles/152" rel="nofollow noreferrer ugc">Learn about addons</a></li><li>View details about the <a href="https://success.vanillaforums.com/kb/articles/151-the-addon-json-file" rel="nofollow noreferrer ugc">addon.json file</a></li><li>Download other addons from the <a href="https://open.vanillaforums.com/addons" rel="nofollow noreferrer ugc">Addon Directory</a> and borrow their code</li><li>Get help in the <a href="https://open.vanillaforums.com/categories/developers" rel="nofollow noreferrer ugc">developer community</a></li></ul><h2 data-id="quickstart-guide">Quickstart guide</h2><p><strong>Higher Logic Vanilla (Vanilla)</strong> 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.</p><h2 data-id="1.-name-your-addon">1. Name your Addon</h2><p>Vanilla generally uses simple names for our addons; we favor descriptive names over clever ones or mini-brands.</p><p>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 <code class="code codeInline" spellcheck="false" tabindex="0">lincolns-fancy-addon</code> or even just <code class="code codeInline" spellcheck="false" tabindex="0">fancyaddon</code>.</p><h2 data-id="2.-define-your-addon">2. Define your Addon</h2><ul><li>Create a folder in the <code class="code codeInline" spellcheck="false" tabindex="0">plugins</code> directory, using the slug name you chose (e.g., <code class="code codeInline" spellcheck="false" tabindex="0">fancyaddon</code>). </li><li>Create a file called <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code>. This file will define basic information about your addon. View <a href="https://success.vanillaforums.com/kb/articles/151-the-addon-json-file" rel="nofollow noreferrer ugc">all of the options</a>. </li><li>Open the file and add the addon information. You can use this as a starting point:</li></ul><pre class="code codeBlock" spellcheck="false" tabindex="0">{ "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" } ] } </pre><p><strong>🛑 IMPORTANT</strong>: The <code class="code codeInline" spellcheck="false" tabindex="0">key</code> value (<code class="code codeInline" spellcheck="false" tabindex="0">fancyaddon</code> above) <strong><em>must exactly match</em></strong> 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.</p><h3 data-id="define-basic-info">Define basic info</h3><ul><li>The <code class="code codeInline" spellcheck="false" tabindex="0">name</code> parameter is optional; it will default to the slug if omitted. To include special characters here or in the description, use their <a href="https://www.w3schools.com/html/html_entities.asp" rel="nofollow noreferrer ugc">HTML entity code</a>.</li><li>Provide a <code class="code codeInline" spellcheck="false" tabindex="0">description</code> that briefly explains what your addon does from the <em>users</em>’ <em>perspective</em>. For <code class="code codeInline" spellcheck="false" tabindex="0">version</code>, familiarize yourself with <a href="http://semver.org/" rel="nofollow noreferrer ugc">semantic versioning</a>.</li><li>The <code class="code codeInline" spellcheck="false" tabindex="0">authors</code> parameters are at your discretion. We recommend using a support address for both the email and URL. <code class="code codeInline" spellcheck="false" tabindex="0">authors</code> takes an array so be sure to include anyone who’s name you want on the addon.</li><li>All further optional parameters described below default to <code class="code codeInline" spellcheck="false" tabindex="0">false</code> if not defined.</li></ul><h3 data-id="define-a-settings-page">Define a settings page</h3><p>To create a “Settings” button that will appear on the addon after it's enabled, add these to your definition:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"settingsUrl": "/settings/somepagehere", "settingsPermission": "Garden.Settings.Manage", </pre><h3 data-id="define-requirements">Define requirements</h3><p>You can require a certain version of Vanilla before your addon can be enabled. To do so, add this:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"require": { "vanilla": ">=3.0" }, </pre><p>You can require other addons to be enabled be using this instead:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"require": { "vanilla": ">=3.0", "Akismet": ">=1.0.1", "StopForumSpam": ">=1.0" }, </pre><p>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 <strong>use defensive programming techniques to guard against missing prerequisites</strong>, rather than simply assuming they will always be there just because you put it in the requirements.</p><h3 data-id="visibility">Visibility</h3><p>If you have <a href="http://vanillaforums.com/" rel="nofollow noreferrer ugc">Vanilla Cloud</a>, make sure to also <a href="https://success.vanillaforums.com/kb/articles/153" rel="nofollow noreferrer ugc">set your addon’s visibility</a>.</p><h3 data-id="define-new-permissions">Define new permissions</h3><p>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 <a href="https://success.vanillaforums.com/kb/articles/255" rel="nofollow noreferrer ugc">using permissions in Vanilla</a> before doing this.</p><p>You can provide an array of permission names using dot syntax. You can optionally use key/value pairs to set a default (<code class="code codeInline" spellcheck="false" tabindex="0">1</code> will give all roles the permission; <code class="code codeInline" spellcheck="false" tabindex="0">0</code> is the default and leaves it off for all roles to start).</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"registerPermissions": { "FancyAddon.Stuff.Add" => 1 }, </pre><p>Or set the default to whether or not the role currently has an existing permission:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">"registerPermissions": { "FancyAddon.Stuff.Add": "Garden.Settings.Manage" }, </pre><p>This allows you to set good defaults while allowing them to be changed independently in the future.</p><h2 data-id="adding-javascript-or-css">Adding JavaScript or CSS</h2><div class="js-embed embedResponsive" data-embedjson="{"body":"Looking to add Javascript & CSS to Vanilla? This is the place to start. There's a few different ways to do this, but some are easier and more optimal. Adding JS inside of an Addon Before continuing with this, you need to have and addon. If you don't have one already, see the Addon Quickstart Guide. Using Typescript Modern…","photoUrl":"https:\/\/us.v-cdn.net\/6030677\/uploads\/VWGAXAF5OFCO\/microsoftteams-image.png","url":"https:\/\/success.vanillaforums.com\/kb\/articles\/165","embedType":"link","name":"Javascript & CSS Quickstart - Vanilla Success"}"> <a href="https://success.vanillaforums.com/kb/articles/165" rel="nofollow noreferrer ugc"> https://success.vanillaforums.com/kb/articles/165 </a> </div> </article> </main>