GuideMe Javascript Toolkit Library

guardianx · Post by **guardianx** » Fri Dec 23, 2016 10:34 pm

Introducing the Javascript Toolkit Library for Guideme.

Javascript Toolkit Libary is a collection of common javascript functions that I've written and found useful over time.

Anyone that's tried to create a GuideMe has probably had to write some javascript. Those that have tried might have noticed that doing certain things in javascript are rather difficult. Many of us have probably started writing our own little libraries to accomplish these things. Rather than everyone writing their own version of common functions, I wanted to share what I have and make it easier for others looking for the same functions.

This library has been extremely helpful to me, I hope this would also be helpful to many others. Below you will find instructions and documentation of all the functions in the toolkit. Enjoy!

Instructions for downloading and adding this library to your tease:

1. Download the zip file here: jstoolkit.zip
2. Extract the .js file to your tease's media folder
3. Include the file to your tease: <Include file="jstoolkit.js" />

Once included, all functions within the toolkit can be accessed via a "js." prefix.
Sample Tease using js.trim() function:

Code: Select all

<Tease>
	<Title>Javascript Toolkit Example</Title>
	<MediaDirectory>Data</MediaDirectory>
	<Include file="jstoolkit.js" />
	<Pages>
		<Page id="start" > 
		  <javascript>
			<![CDATA[
				function pageLoad() {
					var text = js.trim("   Trim Leading and trailing spaces!   ");
					scriptVars.put("vText", "[" + text + "]");
				}
			]]>	
		  </javascript>
		  <Text>
				<span>vText</span>
		  </Text>
		</Page>
	<Pages>
</Tease>

guardianx · Post by **guardianx** » Fri Dec 23, 2016 10:35 pm

Javascript Toolkit Libary Functions
The Javascript Toolkit Library is categorized into the following main categories:

XML Parser - XML Parser Object Collection to support all XML parsing functions.
String Functions - Common functions for manipulating and testing strings.
Files / Folder Functions - Functions for working with files and folders.
Random / Other functions - Functions that involve dealing with random numbers, etc.

XML Parser

Spoiler: show

The XmlParser Object Model offers a an alternative e4x for loading and parsing an XML. It is designed with functions and methods similar to a more commonly used DOMParser used on the web. DOMParser, (and the document object model) is not available in GuideMe javascript engine. The only way to parse XML is e4x. Unfortunately e4x is a little known parser with limited documentation. The XmlParser object provides DOMParser-like XML parsing to guideme.

xmlParser Object
Properties

documentElement - xmlElement containing the root node of the XML document.

Methods

parseFromString(xmlString) - parses an XML from the supplied string.

parseFromFile(xmlFile) - loads and parses an XML file from the supplied xmlFile path. Note: It is important that you ensure your XML file is saved as ANSI or UTF8 encoding only. GuideMe does not properly read files with Byte Order Marks (BOM).

getElementById(val) - Returns an xmlElement whose id attribute matches the supplied value.

getElementsByTagName(tagName) - Returns an array of xmlElements whose XML tagname matches the supplied value. If no match is found, an empty array with length of 0 is returned.

hasChildNodes()
hasChildNodes(tagName) - tagName is optional. If not provided, returns true if XML contains any child elements. If provided, returns true if XML contains any child elements with matching tagName.

getChildNodes()
getChildNodes(tag) - tag is optional. Returns an xmlElement array of child nodes in the XML. If tag is provided, then only xmlElements with matching tagNames are returned. If no child nodes are found, an empty array of length 0 is returned.

getDuplicateIds(tagName) - Given a tagName, checks all the xmlElements with matching tagName for ids that are not unique. Returns a string of the first duplicate id found. If no duplicates are found, an empty string "" is returned.

Example test.xml
Code: Select all
```
<GIRLS>
   <GIRL id="lexi" img="01.jpg/>
   <GIRL id="jane" img="02.jpg/>   
</GIRLS>
```
Code: Select all
```
// Load an xml from file
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromString("test.xml");
```
Code: Select all
```
// Load an xml from string
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromString("<GIRLS><GIRL id='lexi' img='01.jpg'/></GIRLS>");
```
Code: Select all
```
// Load an xml and return the number of GIRL child nodes under the root.
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromString("<GIRLS><GIRL id='lexi'/><GIRL id='jane'/></GIRLS>");
return xmlDoc.getChildNodes("GIRL").length;

returns:
2
```

xmlElement Object
Properties

e4xNode- The e4xNode object that this xmlElement represents.

tagName- This element's tag name.

value- The text content contained in this xml element.

innerText- Returns the content between this element and its end tag, in text-format.

outerText- Returns the content of element, (including tagName, attributes) and its end tag, in text-format.

Methods

hasChildNodes()
hasChildNodes(tagName) - tagName is optional. If not provided, returns true if this element contains any child elements. If tagName is provided, returns true if this element contains any child elements with matching tagName.

getAttribute(attr) - Get the value of the specified attribute in the current element. If not found, an empty string is returned.

setAttribute(attr, value) - Sets the value for a specified attribute in the current element.

getParentNode() - Returns the parent xmlElement of the current element. If no parent is found, a null value is returned.

getNextSibling() - Returns the next xmlElement at the same node tree level.

appendChild(xmlString) - Given an XML string, adds a new child to the XML, as the last child node.

getPrevSibling() - Returns the previous xmlElement at the same node tree level.

getFirstChild() - Returns the first child xmlElement of the current element.

getLastChild - Returns the last child xmlElement of the current element.

getChildNodes()
getChildNodes(tagName) - tagName is optional. Returns an xmlElement array of child nodes in the current element. If tag is provided, then only xmlElements with matching tagNames are returned. If no child nodes are found, an empty array of length 0 is returned.

getElementById(val) - Returns an xmlElement whose id attribute matches the supplied value.

getElementsByTagName(tagName) - Returns an array of xmlElements whose tagname matches the supplied value. If no match is found, an empty array with length of 0 is returned.

Example test.xml
Code: Select all
```
<GIRLS>
   <GIRL id="lexi" img="01.jpg/>
   <GIRL id="jane" img="02.jpg/>   
</GIRLS>
```
Code: Select all
```
// Load an xml, retrieve an element, and return the value of an attribute
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromFile("test.xml");
xmlElem = xmlDoc.getElementById("lexi");
return xmlElem.getAttribute("img");

returns:
"01.jpg"
```
Code: Select all
```
// Retrieve an array of all GIRL elements
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromFile("test.xml");
xmlElements = xmlDoc.getElementsByTagName("GIRL");
return xmlElements;
```
Code: Select all
```
// Adding / setting an attribute
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromFile("test.xml");
xmlElements = xmlDoc.getElementsByTagName("GIRL");
xmlElements[0].setAttribute("hair", "blonde");
```
Code: Select all
```
// Appending a child element.
var xmlDoc = new js.xmlParser();
xmlDoc.parseFromFile("test.xml");
xmlElements = xmlDoc.getElementsByTagName("GIRL");
xmlElements[0].appendChild("<DIALOG>Hello handsome.</DIALOG>");
```

String Functions

Spoiler: show

parseArgs(line) - Parses a comma-separted string and returns an array of arguments. Similar to how DOS command line arguments are parsed, single/double quoted strings are respected and treated as one argument.

Example:

Code: Select all

var line = "a, 'b, c, and d', e";
var args = js.parseArgs(line);

returns array with 3 elements:
["a", "b, c, and d", "e"]

isNumeric(n) - Returns true if a supplied value is numeric.

startsWith(strVal, text) - Returns true of supplied string, strVal, starts with supplied text.

Code: Select all

var s = "Hello World";
return js.startsWith(s, "Hello");

returns:
true

endsWith(strVal, text) - Returns true of supplied string, strVal, ends with supplied text.

trimStart(strVal, chars) - Returns a string of the supplied string, strVal, with the beginning characters trimmed.

Code: Select all

var s = "***Hello World***";
return js.trimStart(s, "*");

returns:
"Hello World***"

trimEnd(strVal, chars) - Returns a string of the supplied string, strVal, with the ending characters trimmed.

Code: Select all

var s = "Hello World***";
return js.trimEnd(s, "*");

returns:
"***Hello World"

trim(strVal) - Returns a string with the surrounding spaces trimmed.

Code: Select all

var s = "     Hello World     ";
return js.trimEnd(s, "*");

returns:
"Hello World"

trim(strVal, char) - Returns a string with the surround char trimmed.

Code: Select all

var s = "***Hello World***";
return js.trim(s, "*");

returns:
"Hello World"

trim(strVal, lchar, rchar) - Returns a string with the beginning lchars trimmed and the ending rchars trimmed.

Code: Select all

var s = "<<<Hello World>>>";
return js.trim(s, "<", ">");

returns:
"Hello World"

htmlEscape(str) - Returns a string with special characters encoded, or escaped.
htmlUnescape(str) - Unescape, or decodes an htmlEscaped string back to its original form.

Files/Folder Functions

Spoiler: show

getFolderPath(filePath) - Given a filepath string, returns path of the containing folder.

Example:

Code: Select all

var file = "/data/images/001.img";
var folder = js.getFolderPath(filePath);
return (folder);

returns:
"/data/images"

getFolders(relativePath)
getFolders(relativePath, includePath) - Given a relative path from the current media directory, returns an array of subfolders at that level. Optional parameter, includePath, is a boolean. When set to true, folders returned will have relativePath included.

Example Folder Structure:

Code: Select all

 |- data
       |- images
       |- video

Code: Select all

//retrieve a list of all folders under data.
var path = "/data";
var folders = js.getFolders(path, true); 
return (folders);

returns:
["data/images","data/videos"]

getFiles(relativePath)
getFiles(relativePath, includePath) - returns an array of files found in the path specified.
includePath - Optional boolean parameter. When set to true, each file in the array will have relativePath included.

Example:

Code: Select all

var path = "/data/images";
var files = js.getFiles(path);
return (files);

returns:
["001.jpg", "002.jpg"]

Code: Select all

var path = "/data/images";
var files = js.getFiles(path, true);
return (files);

returns:
["/data/images/001.jpg", "/data/images/002.jpg"]

Random / Other functions

Spoiler: show

getRandomNumber(min, max) - Returns a random number (integer) between the supplied min and max value.

Code: Select all

var n js.getRandomNumber(0, 3);
return (n);

returns:
[1]

getRandomElement(array) - Given an array, randomly selects an element and returns it.

Code: Select all

var n = ["Lexi", "Jane", "Jill"];
var girl = js.getRandomElement(n);
return (girl);

returns:
"Jane"

shuffleArray(array) - Returns a new array with its elements randomized, or shuffled, like a deck of cards.

Code: Select all

var n = ["Lexi", "Jane", "Jill"];
var girls = js.shuffleArray(n);
return (girls);

returns:
["Jane", "Lexi", "Jill"]

diceRoll(n, d) - Simulates a dice roll. Rolls a d sided dice, n times.

Code: Select all

var dice = 6; //six sided dice
var result = js.diceRoll(3, 6); // roll 6 sided die 3 times. (3d6)
return result;

returns:
13

d3vi0n · Post by **d3vi0n** » Tue Dec 27, 2016 9:06 am

awesome idea!

thx for that!

PlayfulGuy · Post by **PlayfulGuy** » Tue Jan 03, 2017 3:14 pm

Thanks for this. I've been planning on publishing my own collection of functions but never seem to get around to it. Too many projects on the go as always. And then there's the time to document it all $:\'-($

Do you have a more elaborate example of using your xml parser? I fought through e4x and finally managed to figure it out and use it for converting a downloaded tease to my script engine, but it has one bug that I can't fix.
If the downloaded xml contains the <?xml ?> tag at the beginning of the file e4x fails.
If yours works I would rework my code to use this parser.

Thanks again! Some good stuff here.

PG

guardianx · Post by **guardianx** » Wed Jan 04, 2017 5:34 am

PlayfulGuy wrote: Do you have a more elaborate example of using your xml parser? I fought through e4x and finally managed to figure it out and use it for converting a downloaded tease to my script engine, but it has one bug that I can't fix.
If the downloaded xml contains the <?xml ?> tag at the beginning of the file e4x fails.
If yours works I would rework my code to use this parser.

Thanks again! Some good stuff here.

PG

XmlParser still uses e4x underneath the hood. So it inherits all the warts that comes with it, unfortunately. That includes the issue with xml declaration.

The good news, however, is it can be worked around it by simply parsing it out. I updated the parser to do this - so it should work with XML files that contain the tag. You can re-download the toolkit to get an updated version if need be.

Regarding a more elaborate example, I created a working sample tease you can download here:
XMLParser Example

Depending on how much you've done with e4x, you might find converting to use XmlParser not as straight-forward. But ultimately, from my experience, I found it worth it not to have to deal with e4x (though you still can if you want, each XmlElement has an e4xNode property you can access).

PlayfulGuy · Post by **PlayfulGuy** » Thu Jan 05, 2017 3:21 pm

guardianx wrote: XmlParser still uses e4x underneath the hood. So it inherits all the warts that comes with it, unfortunately. That includes the issue with xml declaration.

The good news, however, is it can be worked around it by simply parsing it out. I updated the parser to do this - so it should work with XML files that contain the tag. You can re-download the toolkit to get an updated version if need be.

Regarding a more elaborate example, I created a working sample tease you can download here:
XMLParser Example

Depending on how much you've done with e4x, you might find converting to use XmlParser not as straight-forward. But ultimately, from my experience, I found it worth it not to have to deal with e4x (though you still can if you want, each XmlElement has an e4xNode property you can access).

Thanks, I'll download the toolkit again and look at what you did to parse it out. I tried that angle myself but couldn't get it to work. After parsing out the xml declaration the e4x parser could no longer parse the string and I ended up with an empty xml object. I thought it was some strange behaviour between java strings and javascript strings. Never could figure it out.

I'll check out your sample tease and see how it all works.

Cheers!

GuideMe Javascript Toolkit Library

GuideMe Javascript Toolkit Library

Javascript Toolkit Libary Documentation

Re: GuideMe Javascript Toolkit Library

Re: GuideMe Javascript Toolkit Library

Re: GuideMe Javascript Toolkit Library

Re: GuideMe Javascript Toolkit Library