HackerOne users: Testing against this community violates our program's Terms of Service and will result in your bounty being denied.

For Plugin* Authors: Changes of Interest in Version 2.5

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 :wink:

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" :wink:)

  • 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

Comments

  • R_JR_J Ex-Fanboy Munich Admin

    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_JR_J Ex-Fanboy Munich Admin

    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)... o.O

    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
    }
    
  • rbrahmsonrbrahmson "You may say I'm a dreamer / But I'm not the only one" NY ✭✭✭

    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.

  • RiverRiver MVP
    edited February 2018

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

    addon.json add line

     "isMobile": true,
    

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

  • 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

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

  • rbrahmsonrbrahmson "You may say I'm a dreamer / But I'm not the only one" NY ✭✭✭
    edited February 2018

    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.

  • RiverRiver MVP
    edited February 2018

    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,

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

Sign In or Register to comment.