Add support for widget subclassing

Fixes #3865

core/modules/widgets/widget.js

@@ -22,15 +22,17 @@ Options include:
 	document: optional document object to use instead of global document
 */
 var Widget = function(parseTreeNode,options) {
-	if(arguments.length > 0) {
-		this.initialise(parseTreeNode,options);
-	}
+	this.initialise(parseTreeNode,options);
 };
 
 /*
 Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses
 */
 Widget.prototype.initialise = function(parseTreeNode,options) {
+	// Bail if parseTreeNode is undefined, meaning  that the widget constructor was called without any arguments so that it can be subclassed
+	if(parseTreeNode === undefined) {
+		return;
+	}
 	options = options || {};
 	// Save widget info
 	this.parseTreeNode = parseTreeNode;
@@ -46,7 +48,21 @@ Widget.prototype.initialise = function(parseTreeNode,options) {
 	this.eventListeners = {};
 	// Hashmap of the widget classes
 	if(!this.widgetClasses) {
+		// Get widget classes
 		Widget.prototype.widgetClasses = $tw.modules.applyMethods("widget");
+		// Process any subclasses
+		$tw.modules.forEachModuleOfType("widget-subclass",function(title,module) {
+			if(module.baseClass) {
+				var baseClass = Widget.prototype.widgetClasses[module.baseClass];
+				if(!baseClass) {
+					throw "Module '" + title + "' is attemping to extend a non-existent base class '" + module.baseClass + "'";
+				}
+				var subClass = module.constructor;
+				subClass.prototype = new baseClass();
+				$tw.utils.extend(subClass.prototype,module.prototype);
+				Widget.prototype.widgetClasses[module.name || module.baseClass] = subClass;
+			}
+		});
 	}
 };
 

editions/dev/tiddlers/new/WidgetSubclassingMechanism

@@ -0,0 +1,54 @@
+created: 20190317121937335
+modified: 20190317121937335
+tile: WidgetSubclassingMechanism
+
+!! Introduction
+
+The widget subclassing mechansim allows widgets to be subclassed with additional methods and properties. The subclassed widgets can either overwrite the existing definition of the baseclass widget, or it can be made availabel as a new widget
+
+Widget subclasses are defined in modules of module-type `widget-subclass`. They should export the following properties:
+
+* ''baseClass'': the name of the widget class being subclassed
+* ''name'': (optional) the name to be used for the subclassed widget (defaults to overwriting the baseclass widget)
+* ''constructor'': constructor function for creating the widget object
+* ''prototype'': object whose properties are added to the subclass
+
+!! Example
+
+Here is an example of a subclass of the checkbox widget that adds logging to the event handler:
+
+```
+/*\
+title: $:/my-customised-checkbox-widget.js
+type: application/javascript
+module-type: widget-subclass
+
+Widget base class
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+exports.baseClass = "checkbox"; // Extend the <$checkbox> widget
+
+// Specify a different name to make the subclass available as a new widget instead of overwriting the baseclass:
+// exports.name = "my-enhanced-checkbox";
+
+exports.constructor = function(parseTreeNode,options) {
+	this.initialise(parseTreeNode,options);
+};
+
+exports.prototype = {};
+
+exports.prototype.handleChangeEvent = function(event) {
+	// Call the base class handleChangeEvent function
+	Object.getPrototypeOf(Object.getPrototypeOf(this)).handleChangeEvent.call(this,event);
+	// Print our message
+	console.log("Checkbox status:",this.inputDomNode.checked);
+};
+
+})();
+```