For Plugin* Authors: Changes of Interest in Version 2.5

R_J

Quite a lot has changed with Vanilla version 2.5 and I thought it would be a waste of time if everything that I've already stumbled upon would be forgotten. So I will write it down here.

Before I start: the Vanilla repository on GitHub has a label "Good first contribution". So if you are reading this discussion out of curiosity and not because you are a plugin author, think about becoming one

addon.json

The most obvious change for a developer is the addon.json file. It is already good documented (here and here). The online documentation is getting better and better now and I would be happy if some of the info I pin down here would be carried over to the official docs by some volunteers whose English is good (enough). After all the documentation is just another public repository.
I'll be happy to check your writings if you like to before you contribute.

Here are the keys that are used in the addon.json that I found are used, not all of them are yet in the official docs ("Good first contribution" )

• type
• key
• className (string): If the plugins class isn't named "KeyPlugin" ("key" like the value of the key above) you can give that name here.
• nameSpace: the namespace of the plugin class
• path: the plugin files path
• name
• description
• icon
• iconUrl (url): allows showing an external image in the dashboard
• mobileFriendly
• version
• pluginUrl (string): Shown as a "Visit Site" titled link in the plugin list
• newVersion (string): pluginUrl must be set and it must be a link to the addons application here, otherwise it generates a useless link. Link text is buggy in 2.5, but already fixed in master
• license
• settingsUrl
• usePopupSettings (bool): setting this to false will open the settings page in a new page instead of showing it in a popup
• authors: What is not said there is that "AuthorEmail" is never used anywhere.
• author, authorEmail, authorUrl: don't use them anymore
• require: replaces "RequiredApplications", "RequiredPlugins", "RequiredThemes"
• conflict (array): if you know that your plugin doesn't play well with another plugin you should give the key and the version number here. Implementation isn't working yet (Advanced Editor and Button Bar use it already, but you can activate both of them nevertheless).
• hasLocale (bool): if your plugin has translatable strings
• documentationUrl
• registerPermissions
• priority
• meta (array): if you want to provide additional info that should be displayed in the plugin list

You can surely use whatever key=>value pair you like.

One word of caution: a key that you can see quite often is "settingsPermission", but that has no effect at all! You always have to do permission checks in your public endpoints by yourself. Specifying this key is merely informational and therefore you should consider to stop using it.

By the way: I found this information by looking at
/applications/dashboard/views/settings/helper_functions.php and
/library/Vanilla/Addon.php
and last but not least /cache/addon.php

---

* = this information might also be of interest for theme authors. At least everything you can read about the addon.json file, although there are even more keys available, just look at the class.thememanager.php

R_J

SiteNavModule

Vanilla 2.5 comes with the new "Dashboard v3". Its panel is build with the new SiteNavModule. If your plugin was creating a menu entry in the dashboard (most probably with base_getAppSettingsMenuItems_handler), you should take a look at /applications/vanilla/settings/class.hooks.php->dashboardNavModule_init_handler(). It is a nice example of what you can do with Dashboard v3.

R_J

Deprecated "Things"

Many things get deprecated but only a few are important enough for me to remember/communicate. I will list them below. Additionally a complete "approach" is getting deprecated: Gdn_Factory allowed overriding classes. It is replaced with the modern approach: inversion of control.
I never really understood the factory principle. I hope I will get used to IoC (or never need it)...

Deprecated Functions

• Dashboard->addSideMenu => Dashboard->setHighlightRoute()
• Plugin->getView() => views of plugins should be able to be themed, too. So you need to use other methods. I do not know if this would be sufficient $sender->render('view-name', '', 'plugins/plugin-name');
• discussionUrl() => discussionLink()
• Structure->query() => Structure->executeQuery()
• Model->delete(['SomeID' => 'X']) => Model->deleteID('X')

Deprecated Events

• AfterDiscussionMeta => DiscussionInfo
• InsideCommentMeta => CommentInfo
• AfterCommentMeta => CommentInfo

Deprecated Events

• EventArguments['Object'] = &$Discussion; EventArguments['Type'] = 'Discussion';

• EventArguments['Object'] = &$Comment; EventArguments['Type'] = 'Comment';

Depending on what you need use something like

if (isset($args['Comment'])) {
  // You can work with $args['Comment'] here
} elseif (isset($args['Discussion'])) {
  // Work with $args['Discussion'] here
} else {
  // No discussion and no comment
}

rbrahmson

The following is sample code for rendering views in the different methods before and after Vanilla 2.5:

private function renderview($Sender, $Viewname) {
        if (version_compare(APPLICATION_VERSION, '2.5', '>=')) {    // New method (only in 2.5+)
            $Sender->render($Viewname, '', 'plugins/MyPlugin');      //Note: Viewname specified without ".php"
        } else {
            $Sender->render($this->getView($Viewname.'php'));     //For 2.3 and below add the php extention
        }
    }

I use this function to support plugins running in Vanilla 2.3 and 2.5.

River

for themes to appear in the mobile theme choices instead of desktop choice.

addon.json add line

 "isMobile": true,

River

rj pointed out this tip as well

@River said:
The other thing I found in the plugins for 2.5 is that with some plugins the Settings don't show completely if there are many settings on a separate setting page in views.

You can add "usePopupSettings":false in addon.json (and I expect "UsePopupSettings" => false in PluginInfo) in order to avoid that the setting page will be opened as a popup

rbrahmson

Seems like the ""isMobile": true" addon.json option enables a theme as mobile at the expense of it being a desktop theme. I dislike cloning the theme to have it both ways.

River

Seems like the ""isMobile": true" addon.json option enables a theme as mobile at the expense of it being a desktop theme.

true that is what I indicated.

that is why I stated "instead" of". it means mutually exclusive. obviously vanilla authors found that they wanted things mutually exclusive, otherwise they would have made it additive.

if you are making a mobile theme you may want to know how to make it show in mobile option of dashboard which is
adding

"isMobile": true,