Adding Functionality

Adding Functionality examples for SugarCube (using Macro.Add) and Snowman (Underscore templates).

Summary.md

@@ -16,6 +16,12 @@
 	* [JavaScript](terms/terms_javascript.md)
 	* [Twee](terms/terms_twee.md)
 
+# Adding Functionality
+
+* Adding Functionality
+	* [SugarCube](addingfunctionality/sugarcube/sugarcube_adding_functionality.md)
+	* [Snowman](addingfunctionality/snowman/snowman_adding_functionality.md)
+
 # Audio
 
 * Audio

addingfunctionality/snowman/snowman_adding_functionality.md

@@ -0,0 +1,38 @@
+# "Adding Functionality": Snowman (v1.3.0)
+
+## Summary
+
+Snowman does not provide [macros](../../terms/terms_macros.md). However, additional functionality can be added through the use of the [Underscore.js](https://underscorejs.org/) JavaScript library provided with Snowman.
+
+In this example, a global function, *showCurrentTime()*, is added to the *window.setup* object. It is called in a passage through using the interpolation functionality of [Underscore's template system](https://underscorejs.org/#template) to show a value.
+
+## Live Example
+
+<section>
+<iframe src="snowman_adding_functionality_example.html" height=400 width=90%></iframe>
+
+
+Download: <a href="snowman_adding_functionality_example.html" target="_blank">Live Example</a>
+</section>
+
+## Twee Code
+
+```
+:: StoryTitle
+Adding Functionality in Snowman
+
+:: UserScript[script]
+// Use or create window.setup
+window.setup = window.setup || {};
+
+// Create global function
+window.setup.showCurrentTime = function() {
+	return new Date();
+}
+
+:: Start
+The current time is <%= setup.showCurrentTime() %>
+
+```
+
+Download: <a href="snowman_adding_functionality_twee.txt" target="_blank">Twee Code</a>

addingfunctionality/snowman/snowman_adding_functionality_twee.txt

@@ -0,0 +1,14 @@
+:: StoryTitle
+Adding Functionality in Snowman
+
+:: UserScript[script]
+// Use or create window.setup
+window.setup = window.setup || {};
+
+// Create global function
+window.setup.showCurrentTime = function() {
+	return new Date();
+}
+
+:: Start
+The current time is <%= setup.showCurrentTime() %>

addingfunctionality/sugarcube/sugarcube_adding_functionality.md

@@ -0,0 +1,50 @@
+# "Adding Functionality": SugarCube (v2.18)
+
+## Summary
+
+In SugarCube, additional functionality can be added through the [*Macro.add()*](http://www.motoslave.net/sugarcube/2/docs/api-macro.html#macro-api) function.
+
+In this example, the [*Date()*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) JavaScript function is used to get the current time. This is saved to *payload.contents*, and the [*jQuery.wiki()*](http://www.motoslave.net/sugarcube/2/docs/object-methods.html#jquery-jqueryprotowiki) function is used to convert and append it to the current passage.
+
+## Live Example
+
+<section>
+<iframe src="sugarcube_adding_functionality_example.html" height=400 width=90%></iframe>
+
+
+Download: <a href="sugarcube_adding_functionality_example.html" target="_blank">Live Example</a>
+</section>
+
+## Twee Code
+
+```
+:: StoryTitle
+Adding Functionality in SugarCube
+
+:: UserScript[script]
+Macro.add("currenttime", {
+	tags: null,
+	handler: function() {
+		// Try the following code and catch any errors
+		try {
+    	
+			// Get the current time and save it to the payload
+			this.payload.contents = new Date();
+			
+			// Wikify (and append) the current payload contents
+			jQuery(this.output).wiki(this.payload.contents);
+			
+    	}
+	    catch (ex) {
+			// Return any errors
+	        return this.error("Error: " + ex.message);
+	    }
+	}
+});
+
+:: Start
+<<currenttime>><</currenttime>>
+
+```
+
+Download: <a href="sugarcube_adding_functionality_twee.txt" target="_blank">Twee Code</a>

addingfunctionality/sugarcube/sugarcube_adding_functionality_twee.txt

@@ -0,0 +1,26 @@
+:: StoryTitle
+Adding Functionality in SugarCube
+
+:: UserScript[script]
+Macro.add("currenttime", {
+	tags: null,
+	handler: function() {
+		// Try the following code and catch any errors
+		try {
+
+			// Get the current time and save it to the payload
+			this.payload.contents = new Date();
+
+			// Wikify (and append) the current payload contents
+			jQuery(this.output).wiki(this.payload.contents);
+
+    	}
+	    catch (ex) {
+					// Return any errors
+	        return this.error("Error: " + ex.message);
+	    }
+	}
+});
+
+:: Start
+<<currenttime>><</currenttime>>

terms/terms_macros.md

@@ -1,10 +1,10 @@
 # Macros
 
-For as long as [Twine](../terms/terms_twine.md) has existed, macros have been a part of it. They provide ways to do additional functionality ranging from changing the style of text to dynamically reacting to mouse events. Often, [Story Formats](../terms/terms_storyformats.md) are chosen based on what macros they provide and how they can be used.
+Macros provide ways to do additional functionality ranging from changing the style of text to dynamically reacting to mouse events. Often, [Story Formats](../terms/terms_storyformats.md) are chosen based on what macros they provide and how they can be used together.
 
 ## Twine 1 and SugarCube
 
-Originally, macros were written with two less-than (```<<```) and two-greater-than signs (```>>```) around the keyword. ([SugarCube](../terms/terms_storyformats.md), as a successor of this form, follows the same syntax.)
+In Twine 1, macros were written with two less-than (```<<```) and two-greater-than signs (```>>```) around the keyword. ([SugarCube](../terms/terms_storyformats.md), as a successor of this form, follows the same syntax.)
 
 **Example:**
 ```

terms/terms_twee.md

@@ -24,7 +24,7 @@ Charlie Brown is a person in the comic Peanuts
 
 ## Special Passage Names
 
-Because Twee does not currently have a specification, some compilers understand and process certain keywords differently. The following is a common set of reserved passage names.
+Because Twee does not currently have a specification, some compilers understand and process certain keywords differently. The following is a common set of reserved passage names. In each case, capitalization matters: "storytitle" is not the same as "StoryTitle".
 
 #### Start
 
@@ -135,7 +135,9 @@ In Twine 2, this passage is the equivalent of Story JavaScript.
 
 ## Special Tag Names
 
-Most Twee compilers understand two common tag names, stylesheet and script. These are usually loaded and run from passages tagged with them in alphabetical order.
+Most Twee compilers understand two common tag names, stylesheet and script. In each case, the tag names are lowercase.
+
+Passages are also loaded according to alphabetical order if others exist with the same special keywords in their own tags.
 
 #### Stylesheet