GuideMe Javascript Toolkit Library

Webteases are great, but what if you're in the mood for a slightly more immersive experience? Chat about Tease AI and other offline tease software.

Moderator: 1885

Post Reply
guardianx
Explorer
Explorer
Posts: 32
Joined: Sun Mar 30, 2014 7:24 pm

GuideMe Javascript Toolkit Library

Post by guardianx »

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>
Last edited by guardianx on Sat Feb 04, 2017 2:08 am, edited 3 times in total.
guardianx
Explorer
Explorer
Posts: 32
Joined: Sun Mar 30, 2014 7:24 pm

Javascript Toolkit Libary Documentation

Post by guardianx »

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
User avatar
d3vi0n
Explorer At Heart
Explorer At Heart
Posts: 563
Joined: Fri Mar 25, 2011 10:42 am

Re: GuideMe Javascript Toolkit Library

Post by d3vi0n »

awesome idea! :w00t: thx for that! :wave:
Try GuideMe to play Milovana Teases offline or create your own offline teases with highres images and videos...
Look at Hearts Club or Pilgrim Quest or My Succubus if you wanna see whats possible with GuideMe...
User avatar
PlayfulGuy
Explorer At Heart
Explorer At Heart
Posts: 778
Joined: Sat Jul 07, 2012 10:08 pm
Gender: Male
Sexual Orientation: Bisexual/Bi-Curious
I am a: Switch
Dom/me(s): No domme
Sub/Slave(s): No sub
Location: British Columbia, Canada

Re: GuideMe Javascript Toolkit Library

Post by PlayfulGuy »

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
Explorer
Explorer
Posts: 32
Joined: Sun Mar 30, 2014 7:24 pm

Re: GuideMe Javascript Toolkit Library

Post by guardianx »

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).
User avatar
PlayfulGuy
Explorer At Heart
Explorer At Heart
Posts: 778
Joined: Sat Jul 07, 2012 10:08 pm
Gender: Male
Sexual Orientation: Bisexual/Bi-Curious
I am a: Switch
Dom/me(s): No domme
Sub/Slave(s): No sub
Location: British Columbia, Canada

Re: GuideMe Javascript Toolkit Library

Post by PlayfulGuy »

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!
Post Reply

Who is online

Users browsing this forum: No registered users and 16 guests