Add requiresVersion property to module API.

2025-06-27 11:50:00 +00:00 · 2016-10-13 16:42:15 +02:00 · 2016-10-13 16:42:15 +02:00 · 95edbc16bb
commit 95edbc16bb
parent 15a5e3c779
8 changed files with 169 additions and 52 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -9,13 +9,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - Finnish translation.
 - Danish translation.
- Method to overwrite the module's header. [See documentation.](https://github.com/MichMich/MagicMirror/tree/develop/modules#getheader)
 - Option to limit access to certain IP addresses based on the value of `ipWhitelist` in the `config.js`, default is access from localhost only (Issue [#456](https://github.com/MichMich/MagicMirror/issues/456)).
 - Added ability to change the point of time when calendar events get relative.
 - Add Splash screen on boot.
 - Add option to show humidity in currentWeather module.
- Add Visibility locking to module system. See [documentation](https://github.com/MichMich/MagicMirror/tree/develop/modules#visibility-locking) for more information.
 - Add VSCode IntelliSense support.
+- Module API: Add Visibility locking to module system. [See documentation](https://github.com/MichMich/MagicMirror/tree/develop/modules#visibility-locking) for more information.
+- Module API: Method to overwrite the module's header. [See documentation](https://github.com/MichMich/MagicMirror/tree/develop/modules#getheader) for more information.
+- Module API: Option to define the minimumn MagicMirror verion to run a module. [See documentation](https://github.com/MichMich/MagicMirror/tree/develop/modules#requiresVersion) for more information.

 ### Updated
 - Modified translations for Frysk.
--- a/index.html
+++ b/index.html
@ -8,6 +8,10 @@
 	<link rel="stylesheet" type="text/css" href="css/main.css">
 	<link rel="stylesheet" type="text/css" href="fonts/roboto.css">
 	<!-- custom.css is loaded by the loader.js to make sure it's loaded after the module css files. -->
+
+	<script type="text/javascript">
+		var version = "#VERSION#";
+	</script>
 </head>
 <body>
 	<div class="region fullscreen below"><div class="container"></div></div>
--- a/js/app.js
+++ b/js/app.js
@ -10,6 +10,10 @@ var Server = require(__dirname + "/server.js");
 var defaultModules = require(__dirname + "/../modules/default/defaultmodules.js");
 var path = require("path");

+// Get version number.
+global.version = JSON.parse(fs.readFileSync("package.json", "utf8")).version;
+console.log("Starting MagicMirror: v" + global.version);
+
 // The next part is here to prevent a major exception when there
 // is no internet connection. This could probable be solved better.
 process.on("uncaughtException", function (err) {
@ -82,6 +86,17 @@ var App = function() {
 		if (loadModule) {
 			var Module = require(helperPath);
 			var m = new Module();
+
+			if (m.requiresVersion) {
+				console.log("Check MagicMirror version for node helper '" + moduleName + "' - Minimum version:  " + m.requiresVersion + " - Current version: " + global.version);
+				if (cmpVersions(global.version, m.requiresVersion) >= 0) {
+					console.log("Version is ok!");
+				} else {
+					console.log("Version is incorrect. Skip module: '" + moduleName + "'");
+					return;
+				}
+			}
+
 			m.setName(moduleName);
 			m.setPath(path.resolve(moduleFolder));
 			nodeHelpers.push(m);
@ -103,6 +118,28 @@ var App = function() {
 		console.log("All module helpers loaded.");
 	};

+	/* cmpVersions(a,b)
+	 * Compare two symantic version numbers and return the difference.
+	 *
+	 * argument a string - Version number a.
+	 * argument a string - Version number b.
+	 */
+	function cmpVersions(a, b) {
+		var i, diff;
+		var regExStrip0 = /(\.0+)+$/;
+		var segmentsA = a.replace(regExStrip0, "").split(".");
+		var segmentsB = b.replace(regExStrip0, "").split(".");
+		var l = Math.min(segmentsA.length, segmentsB.length);
+
+		for (i = 0; i < l; i++) {
+			diff = parseInt(segmentsA[i], 10) - parseInt(segmentsB[i], 10);
+			if (diff) {
+				return diff;
+			}
+		}
+		return segmentsA.length - segmentsB.length;
+	}
+
 	/* start(callback)
 	 * This methods starts the core app.
 	 * It loads the config, then it loads all modules.
--- a/js/loader.js
+++ b/js/loader.js
@ -117,9 +117,13 @@ var Loader = (function() {

 		var afterLoad = function() {
 			var moduleObject = Module.create(module.name);
+			if (moduleObject) {
 				bootstrapModule(module, moduleObject, function() {
 					callback();
 				});
+			} else {
+				callback();
+			}
 		};

 		if (loadedModuleFiles.indexOf(url) !== -1) {
--- a/js/module.js
+++ b/js/module.js
@ -14,6 +14,9 @@ var Module = Class.extend({
 	 * All methods (and properties) below can be subclassed. *
 	 *********************************************************/

+	// Set the minimum MagicMirror module version for this module.
+	requiresVersion: "2.0.0",
+
 	// Module config defaults.
 	defaults: {},

@ -363,6 +366,11 @@ Module.definitions = {};

 Module.create = function (name) {

+	// Make sure module definition is available.
+	if (!Module.definitions[name]) {
+		return;
+	}
+
 	//Define the clone method for later use.
 	function cloneObject(obj) {
 		if (obj === null || typeof obj !== "object") {
@ -387,7 +395,39 @@ Module.create = function(name) {

 };

+/* cmpVersions(a,b)
+* Compare two symantic version numbers and return the difference.
+*
+* argument a string - Version number a.
+* argument a string - Version number b.
+*/
+function cmpVersions(a, b) {
+	var i, diff;
+	var regExStrip0 = /(\.0+)+$/;
+	var segmentsA = a.replace(regExStrip0, "").split(".");
+	var segmentsB = b.replace(regExStrip0, "").split(".");
+	var l = Math.min(segmentsA.length, segmentsB.length);
+
+	for (i = 0; i < l; i++) {
+		diff = parseInt(segmentsA[i], 10) - parseInt(segmentsB[i], 10);
+		if (diff) {
+			return diff;
+		}
+	}
+	return segmentsA.length - segmentsB.length;
+}
+
 Module.register = function (name, moduleDefinition) {
+
+	if (moduleDefinition.requiresVersion) {
+		Log.log("Check MagicMirror version for module '" + name + "' - Minimum version:  " + moduleDefinition.requiresVersion + " - Current version: " + version);
+		if (cmpVersions(version, moduleDefinition.requiresVersion) >= 0) {
+			Log.log("Version is ok!");
+		} else {
+			Log.log("Version is incorrect. Skip module: '" + name + "'");
+			return;
+		}
+	}
 	Log.log("Module registered: " + name);
 	Module.definitions[name] = moduleDefinition;
 };
--- a/js/server.js
+++ b/js/server.js
@ -11,6 +11,7 @@ var server = require("http").Server(app);
 var io = require("socket.io")(server);
 var path = require("path");
 var ipfilter = require("express-ipfilter").IpFilter;
+var fs = require("fs");

 var Server = function(config, callback) {
 	console.log("Starting server op port " + config.port + " ... ");
@ -35,8 +36,15 @@ var Server = function(config, callback) {
 	app.use("/vendor", express.static(path.resolve(__dirname + "/../vendor")));
 	app.use("/translations", express.static(path.resolve(__dirname + "/../translations")));

+	app.get("/version", function(req,res) {
+		res.send(global.version);
+	});
+	
 	app.get("/", function(req, res) {
-		res.sendFile(path.resolve(__dirname + "/../index.html"));
+		var html = fs.readFileSync(path.resolve(__dirname + "/../index.html"), {encoding: "utf8"});
+		html = html.replace("#VERSION#", global.version);
+
+		res.send(html);
 	});

 	if (typeof callback === "function") {
--- a/modules/README.md
+++ b/modules/README.md
@ -78,6 +78,16 @@ The data object contains additional metadata about the module instance:
 ####`defaults: {}`
 Any properties defined in the defaults object, will be merged with the module config as defined in the user's config.js file. This is the best place to set your modules's configuration defaults. Any of the module configuration properties can be accessed using `this.config.propertyName`, but more about that later.

+####'requiresVersion:'
+
+*Introduced in version: 2.1.0.*
+
+A string that defines the minimum version of the MagicMirror framework. If it is set, the system compares the required version with the users version. If the version of the user is out of date, it won't run the module. Make sure to also set this value in the Node helper. 
+
+**Note:** Since this check is introduced in version 2.1.0, this check will not be run in older versions. Keep this in mind if you get issue reports on your module.
+
+Example: `"2.1.0"`
+
 ### Subclassable module methods

 ####`init()`
@ -286,7 +296,7 @@ this.sendSocketNotification('SET_CONFIG', this.config);
 ####`this.hide(speed, callback, options)`
 ***speed* Number** - Optional (Required when setting callback or options), The speed of the hide animation in milliseconds.
 ***callback* Function** - Optional, The callback after the hide animation is finished.
-***options* Function** - Optional, Object with additional options for the hide action (see below).
+***options* Function** - Optional, Object with additional options for the hide action (see below). (*Introduced in version: 2.1.0.*)

 To hide a module, you can call the `hide(speed, callback)` method. You can call the hide method on the module instance itself using `this.hide()`, but of course you can also hide another module using `anOtherModule.hide()`.

@ -303,7 +313,7 @@ Possible configurable options:
 ####`this.show(speed, callback, options)`
 ***speed* Number** - Optional (Required when setting callback or options), The speed of the show animation in milliseconds.
 ***callback* Function** - Optional, The callback after the show animation is finished.
-***options* Function** - Optional, Object with additional options for the show action (see below).
+***options* Function** - Optional, Object with additional options for the show action (see below). (*Introduced in version: 2.1.0.*)

 To show a module, you can call the `show(speed, callback)` method. You can call the show method on the module instance itself using `this.show()`, but of course you can also show another module using `anOtherModule.show()`.

@ -317,6 +327,9 @@ Possible configurable options:
 **Note 3:** If the dom is not yet created, the show method won't work. Wait for the `DOM_OBJECTS_CREATED` [notification](#notificationreceivednotification-payload-sender).

 ####Visibility locking
+
+(*Introduced in version: 2.1.0.*)
+
 Visiblity locking helps the module system to prevent unwanted hide/show actions. The following scenario explains the concept:

 **Module B asks module A to hide:**
@ -450,6 +463,16 @@ this.expressApp.use("/" + this.name, express.static(this.path + "/public"));

 This is a link to the IO instance. It will allow you to do some Socket.IO magic. In most cases you won't need this, since the Node Helper has a few convenience methods to make this simple.

+
+####'requiresVersion:'
+*Introduced in version: 2.1.0.*
+
+A string that defines the minimum version of the MagicMirror framework. If it is set, the system compares the required version with the users version. If the version of the user is out of date, it won't run the module.
+
+**Note:** Since this check is introduced in version 2.1.0, this check will not be run in older versions. Keep this in mind if you get issue reports on your module.
+
+Example: `"2.1.0"`
+
 ### Subclassable module methods

 ####`init()`
--- a/package.json
+++ b/package.json
@ -1,6 +1,6 @@
 {
  "name": "magicmirror",
-  "version": "2.0.0",
+  "version": "2.1.0",
  "description": "A modular interface for smart mirrors.",
  "main": "js/electron.js",
  "scripts": {