CA "API" for plugin update checks

[Squid]

NOTE:  As of unRaid 6.8.0-rc1, these functions are now included in the base OS  (the plugin update checks and the banner warning system)

 

Not really an API, but with the release of CA versions 2019.03.27+,  I'm making available to any plugin a function to toss up a banner if the plugin is out of date 

 

This is not a replacement for the built-in plugin update notification system, but an extension of it.  The banner only appears when the user is on the .page file for a plugin, and the check runs in the background so as to not interfere / slowdown any other scripts you may be running  (Side effect is that this banner is less disturbing on CA's own page when an update becomes available than it's previous banner used for this purpose)

 

 

All a plugin dev has to do is add in the following code to their page file to utilize this at the basic level.  

$(function() {
  if ( typeof caPluginUpdateCheck === "function" ) {
    caPluginUpdateCheck("fix.common.problems.plg");
  }
});

However, since not all plugins have their own page and are rather inserted as tabs into an existing page, then the option exists to specify a div to place the upgrade notice instead to only have it appear on their own tab (ie: the main page for UD)

 

$(function() {
  if ( typeof caPluginUpdateCheck === "function" ) {
    caPluginUpdateCheck("ca.mover.tuning.plg",{element:".pluginUpdate"});
  }
});
...
<div class='pluginUpdate'></div>

  

The complete usage is as follows:

caPluginUpdateCheck("fileNameOfPlg",{options},callback(result));

Options are as follows

name: string /* name of the plugin - if not present, defaults to fileNameOfPlg  - Recommended to use*/
element: DOM element/class /* if present, the banner shows up in whatever div you specify */
noDismiss: true | false /* if true, then the dismiss "x" will not appear - defaults to false */
dontShow: true | false /* if true, then the banner will not appear under any circumstance - defaults to false, only useful when using callbacks */
debug: true | false /* forces the banner to always show - defaults to false */


The callback function if present is passed a JSON string of
{
  updateAvailable: true | false,
  version: "version of update",
  min: "minimum OS version that the update requires",
  changes: "the changelog from the update",
  installedVersion: "currently installed version"
}

The callback function allows you to do whatever you want with the information provided - I use the callback on many of my plugins to have the currently installed version displayed somewhere on the page if some one has problems and posts a screenshot

caPluginUpdateCheck("community.applications.plg",{noDismiss:true,name:"Community Applications"},function(data) {
  if (data) {
    var result = JSON.parse(data);
    $("#caInstalledVersion").html(result.installedVersion);
  }
});

 

Notes:

 

The code snips will NOT cause any problems if CA is not installed, or if it hasn't been updated (ie: the test for if the function exists)

 

If the plugin's minimum OS version specified is greater than the currently installed OS version, then the updateAvailable will always be false, and the banner will not appear (You can test for this if updateAvailable == false and version > installedVersion)

 

This function is not dependent upon plugin update checks being enabled in unRaid, nor a check for updates ever having been performed by the user.  The results are always live, and are only performed when hitting the page file for the plugin in question.

 

Dismissing of updates is handled via a cookie that expires when the user's browser session closes.  But, if the banner is dismissed and another update becomes available then the banner will reappear.

 

[Squid]

Today's Update to CA (2019.08.05) opens up a few more functions for plugin authors to use

 

addBannerWarning and removeBannerWarning

 

These functions allow a plugin author to add a warning across the unRaid banner to display any important warnings, etc (ie: something like "A reboot is required for changes to take effect")

 

Usage is simple:

 

if (typeof addBannerWarning === "function" ) {
  addBannerWarning("A Reboot Is Required For These Changes To Take Effect");
}

This will automatically add a little warning symbol prior to the message and also allow the user to dismiss the warning by clicking a little "x" at the right

 

If you want your plugin to be able to remove the banner if circumstances change, then you'll change the syntax slightly:

if (typeof addBannerWarning === "function" ) {
  var myWarning = addBannerWarning("A Reboot Is Required For These Changes To Take Effect");
}
.
.
.
if (typeof removeBannerWarning === "function" ) {
  removeBannerWarning(myWarning);
}

You can also slightly customize slightly the options with the warnings:

 

addBannerWarning(text,warning=true,noDismiss=false)

warning = true|false will select whether or not to display the little warning icon prior to the warning text

noDismiss = true|false will select whether or not the warning is dismiss-able or not

 

A dismiss-able warning is handled via a cookie that expires at the end of the session.  If the user has dismissed the warning, then so long as that session is active, the warning will not re-appear

 

Any dismiss-able warning should be unique, as the cookie that determines whether or not the warning has been dismissed is the alphanumeric text of the warning (sans spaces, special characters, etc)

 

If there are multiple warnings or upgrade notices, then the browser will cycle through them all with a delay of 10 seconds.

 

* Note:  All banner warnings take place in the banner itself.  It is not possible to relocate them to a separate element.

 

If you want to see this in action, go to settings - Docker and disable the docker service then go to the Apps Tab.

 

 

[Squid]

Added another function for plugin authors to utilize (currently available if CA version 2020.01.18+ is installed, but will soon issue a PR for it to be included in the base OS)

 

Currently, any notifications that the server must be rebooted are not consistent when switching back and forth between pages (with the exception of notices because the OS was updated, any notification gets lost when leaving the page - including some built-in pages within unRaid).  With this function, a plugin author can easily throw up a Reboot is necessary message and have that survive from page to page in the GUI until the user actually reboots.

 

	if (typeof addRebootNotice === "function") {
		addRebootNotice();
	}

will toss up a banner warning on all GUI pages "A reboot is required for the changes to take effect"

 

You can also customize the message (recommended)

	if (typeof addRebootNotice === "function") {
		addRebootNotice("Disable Security Mitigations: A Reboot Is Required For Changes To Take Effect");
	}

For complete backwards compatibility with previous versions of CA / unRaid, change the code to be something akin to this:

	if (typeof addRebootNotice === "function") {
		addRebootNotice("Disable Security Mitigations: A Reboot Is Required For Changes To Take Effect");
	} else {
		if (typeof addBannerWarning === "function") {
			addBannerWarning("A Reboot Is Required For Changes To Take Effect");
		}
	}

The fallback of addBannerWarning will however only display on the current page within the GUI

[Squid]

The next release of unRaid will have the addRebootNotice() function built-in, along with a method to remove it if the circumstances change

 

removeRebootNotice(string) will be remove the notice previously added.  Note that the string being passed must be 100% identical to what was originally added via addRebootNotice

 

ie:

 

$.post("/plugins/dynamix.vm.manager/include/VMajax.php", {action:'reboot'}, function(data){
 var rebootMessage = "VM Settings: A reboot is required to apply changes";
 if (data.modified)
   addRebootNotice(rebootMessage);
 else
   removeRebootNotice(rebootMessage);
});

To maintain compatibility with previous versions of unRaid, you should wrap those functions around 

if (typeof removeRebootNotice === "function")
.
.