Merge pull request #1678 from felixhayashi/feature/vars_widget

Introducing the vars widget

core/modules/widgets/vars.js

@@ -0,0 +1,75 @@
+/*\
+title: $:/core/modules/widgets/vars.js
+type: application/javascript
+module-type: widget
+
+This widget allows the user to set multiple variables in one go.
+
+```
+\define helloworld() Hello world!
+<$vars greeting="Hi" me={{!!title}} sentence=<<helloworld>>>
+  <<greeting>>! I am <<me>> and I say: <<sentence>>
+</$vars>
+```
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+var Widget = require("$:/core/modules/widgets/widget.js").widget;
+
+var VarsWidget = function(parseTreeNode,options) {
+	// Call the constructor
+	Widget.call(this);
+	// Initialise	
+	this.initialise(parseTreeNode,options);
+};
+
+/*
+Inherit from the base widget class
+*/
+VarsWidget.prototype = Object.create(Widget.prototype);
+
+/*
+Render this widget into the DOM
+*/
+VarsWidget.prototype.render = function(parent,nextSibling) {
+	this.parentDomNode = parent;
+	this.computeAttributes();
+	this.execute();
+	this.renderChildren(parent,nextSibling);
+};
+
+/*
+Compute the internal state of the widget
+*/
+VarsWidget.prototype.execute = function() {
+	// Parse variables
+	var self = this;
+	$tw.utils.each(this.attributes,function(val,key) {
+		if(key.charAt(0) !== "$") {
+			self.setVariable(key,val);
+		}
+	});
+	// Construct the child widgets
+	this.makeChildWidgets();
+};
+
+/*
+Refresh the widget by ensuring our attributes are up to date
+*/
+VarsWidget.prototype.refresh = function(changedTiddlers) {
+	var changedAttributes = this.computeAttributes();
+	if(Object.keys(changedAttributes).length) {
+		this.refreshSelf();
+		return true;
+	}
+	return this.refreshChildren(changedTiddlers);
+};
+
+exports["vars"] = VarsWidget;
+
+})();

editions/prerelease/tiddlers/VarsWidget.tid

@@ -0,0 +1,52 @@
+title: VarsWidget
+created: 20150426115958020
+modified: 20150426115958020
+tags: Widgets
+caption: vars
+
+! Introduction
+
+The ''vars'' widget allows you to set multiple variables in one go. It thereby reduces code complexity that would arise when setting
+many variables using the [[SetWidget]].
+
+! Content and Attributes
+
+The content of the `<$vars>` widget is the scope for the value assigned to the variable.
+
+|!Attribute |!Description |
+|//{attributes not starting with $}// |Each attribute name specifies a variable name. The attribute value is used as variable assignement |
+
+! Examples
+
+Consider a case where you need to set multiple variables.
+
+Using the `<$vars>` widget, this situation may be handled in the following way:
+
+```
+\define helloworld() Hello world!
+
+<$vars greeting="Hi" me={{!!title}} sentence=<<helloworld>>>
+  <<greeting>>! I am <<me>> and I say: <<sentence>>
+</$vars>
+```
+
+In contrast, here is the same example, but using the `<$set>` widget instead:
+
+```
+<$set name="greeting" value="Hi" />
+<$set name="me" value={{!!title}} />
+<$set name="sentence" value=<<helloworld>> />
+  <<greeting>>! I am <<me>> and I say: <<sentence>>
+</$set>
+</$set>
+</$set>
+```
+
+
+! Remarks
+
+It should be noted that this widget differs from the set widget in the following ways:
+
+* You cannot specify a fallback (also known as "emptyValue")
+* You cannot use a filter to produce a conditional variable assignement
+