YOU, yes you, can create new things for the Moose to say!

The new Moose has a built-in Javascript interpreter which allows new abilities to be added, without re-compiling the moose project. It’s a great feature.

 
 

Here is the documentation.

Javascript functions for

Reading the Settings.xml file

Lets start at the beginning. All the files necessary for a plugin, are stored in a folder named for the plugin. When you create a new plugin, you get a new folder with new files to customize.

 
 

A special file called Settings.xml is in each plugin’s folder, and it can flexibly store quite a lot of kinds of data, and the Moose’s javascript provides some special functions to make it easy to get that data.

 
 

// Get Settings from the Settings.xml file in the plugin’s folder.
var settings = Resources.Settings;

The file Settings.xml is read from disk into a C# data structure for the plugin, even before the plugin does it’s StartUp function, so this call inside javascript to settings = Resources.Settings; does not cause a disk read.

 
 

 

The GetSetting() and GetAllSettings() functions

In the GetSetting() function, the parameter can be Tag name or Id number of the Tag, ( optionally preceded by a path ). ( Tag names must be defined in Tags.xml, before you can use them. )

The Tags.xml file, is another special file in the plugin’s folder. Javascript can’t create Tags, which is a security feature. All settings are length-checked to prevent buffer overflow exploits.

GetSetting() can have a single parameter like “holidaylist”, or it can also be a list of parameters that describe a path to a final Setting value or Settings group. ( more about paths below. )

 

var holidaylist = settings.GetSetting("holidaylist"); // an example with a single parameter.

Before you can use custom tag names like “<holidaylist>”, they need to be added into the Tags.xml file.

Internally GetSetting(parameter) will treat all parameters as alphanumeric, and use string matching to find the desired thing.

GetSetting() returns an individual SettingGroup, ( type is Element ) that contains subordinate XML settings. It won’t return the actual value of an individual setting. (Use GetValue() for values.)

For example holiday.GetSetting("todayphrase"); won’t work when <todayphrase>It’s Friday.</todayphrase> is holding only a value (a string). GetSetting does work when there are nested settings-Groups inside it.

To test for success from theSetting = mySettings.GetSetting("WhatIWant");, use if ( theSetting ). ( Note that theSetting.Length won’t work. )

GetAllSettings() returns an array of settings that share the same name. Then you can For-Loop through them. Here’s an example.

 

var usHolidays = Resources.Settings.GetAllSettings(“holidays”, “us_holidays”, “holiday”);
for(var i = 0; i < usHolidays.Length; i++) {
   var currentHoliday = usHolidays[i];
   if(currentHoliday.GetValue(“date”) == “01/01/01”) {
     Say(“Go home!”);
   }
}

Paths as multiple parameters

As the above example shows, both GetSetting() and GetAllSettings() can have multiple parameters, that name the various levels going deeper into the XML structure. The final parameter is always the desired one to retrieve.


Resources.Settings.GetSetting(“holidays”);
Resources.Settings.GetSetting(“holidays”, ”holiday”);
Resources.Settings.GetSetting(“root”, ”level2” , ”level3” , ”level4” , ”level5” , ”level6”, etc…);


One extra function is GetRandomSetting(path) that will pick one at random and return it.

Another function is GetShuffledSetting(path) which will random-shuffle the Settings, and return a Setting sequentially, which is nice to give a random feeling, but prevent getting the same thing twice in a row. It will automatically random-shuffle them again when the first sequence is used up.

 
 

 

GetSettingById(path)

Another extra function is GetSettingById(path), which uses the Id= attribute inside of a setting tag. The purpose of this is to allows the Tag names to be translated into other languages, if someone desired to do that. The Id wouldn't change, the code wouldn't change, and the Settings.xml might become more readable in other languages by doing so, which might make maintenance easier in foreign languages.

This GetSettingsById() and below, GetSettingsByTagId, and GetValueByTagId(), were ideas that so-far, haven't been useful in real life. I haven't worked on any translating to other languages yet, and I might not ever do that, because APIs can now do translating pretty well.

 

GetSettingsByTagId() and GetValueByTagId()

GetSettingsByTagId() and GetValueByTagId() are specifically for using the Ids in Tags.xml.

 

Resourcs.Settings.GetLength("Jokes","String")

Resourcs.Settings.GetLength("Jokes","String") would return the number of <String> inside <Jokes>...<Jokes>. There is a different way, which is to load all the strings into an array using: theStrings = Resources.Settings.GetAllValues("Jokes","String"); and then use theStrings.length.

 

The GetValue() and GetAllValues() functions

These functions get actual string values. All values arrive in javascript variables as strings.


var funcId = group.GetValue(“functionid”);
if(funcId) {
   // We have it.
} else {
   // We don’t.
}


The GetAllValues("someValue") will return an array. Each array element contains a string.

And GetRandomValue("someValue") will return one randomly, if there were several with same name. This is incredibly useful for Strings to be spoken by the Moose. It's lovely to have random variations in what is spoken.

And GetShuffledValue("String") will return the next string in the shuffled-random sequence, which is great for jokes, so you don't hear a joke repeat until after you've heard them all.

Similar to GetSetting() and GetAllSettings(), the GetValue() and GetAllValues() and GetRandomValue() and GetShuffledValue() functions can accept multiple parameters to let you step deeper into an XML structure. For example:

var date = Resources.Setting.GetValue(“holidays”, “holiday”, “date”);

 

GetValueById(path)

One more function is GetValueById(path); for using the Id= attribute inside of tag setting, rather than it's tag name, ie, so you can translate tag names into other languages, so that Settings are more easily understood in non-English languages.

 

SetValue()

There is also a SetValue() command. Here's an example:

<Settings>
   <holidays>
     <us_holidays>
       <holiday>
         <date>01/01/01</date>
         <type>1</type>
       </holiday>
     </us_holidays>
   </holidays>
</Settings>


Resources.Settings.SetValue(“holidays”, “us_holidays”, “holiday”, “date”, “02/02/02”);

What about Create, Delete, Rename, Copy of Settings?

RemoveSetting(path); is available, but
We don't yet have Create, Rename, Copy implemented in javascript for settings, and we might not ever do that. Those are entering into database-y functionality, and for everyone's security peace-of-mind, it's probably better for plugins to use some external cloud API for storing datasets that can expand. Example services from Box.com, Dropbox.com and others, come to mind.

 

You can use Resources.Settings.. in javascript and in HTML view <script>s

Creating the Settings.xml file

Settings.xml is an XML format file. All the tags you use, must be defined in Tags.xml. Consider the examples of tags called <StringGroup> and <String> .

All Tags (for example, like <StringGroup> and <String> ) can optionally have Id=, or Comment= placed inside the tag. ( and also ShuffleIndex= and data-setting=, see below ).

The Id= parameter is an alphanumeric, and it is matched using string-matching code internally.

 

Shuffle Index

Shuffling is wonderful. It seems a little better than using Random(), and Shuffling will save it's position and ordering between sessions. To do this saving, it inserts extra XML tags into the Settings.xml file. They look like this:
<ShuffleData>
   <Target>String</Target>
   <Index>4</Index>
</ShuffleData>

If your javascript code uses GetShuffledValue(), then the <ShuffleData> gets automatically inserted into your Settings.xml, which is a suprise at first. And it can also re-order your values whenever the shuffle sequence needs to be re-shuffled again, and that is also a suprise, when you notice that the values you typed into Settings.xml, were re-ordered mysteriously.

 

data-setting=

Further below, there is another kind: data-setting=, that is used designate: that the value inside this tag is supposed to be automatically set into the User Interface HTML of the plugins, usually the values go into <input> areas like textarea or checkboxes.

 

Here's are simple XML examples:

<StringGroup Id="1" Comment="primary fun" />
<StringGroup Id="StringGroup" Comment="secondary pain" />

and here's a different example:
( And notice it shows us that empty lines of whitespace are OK, and shows that Id can look like a number or a word. )

<StringGroup>
   <StringGroup Id="1">
     <String Id="1">Group 1 String 1</String>
     <String Id="2">Group 1 String 2</String>
   </StringGroup>

   <StringGroup Id="Group 2">
     <StringGroup Id="Inner Group">
       <String Id="1">Group 2 Inner Group String 1</String>
       <String Id="2">Group 2 Inner Group String 2</String>
     </StringGroup>

     <String Id="1">Group 2 String 1</String>
     <String Id="2">Group 2 String 2</String>

     </StringGroup>

   <String Id="2">Root Group String 1</String>
   <String Id="2">Root Group String 2</String>

</StringGroup>

An important rule. There can be only 1 outer <Settings> tag in the Settings.xml file. If you try to put 2 or more at the root level, everything past #1 Settings group gets deleted, which is really confusing to see your work just disappear. The inventors of XML dictated, thou shalt have but 1 root tag in XML.

The characters inside of XML tags like <String>....</String> cannot have embedded < or > inside. But they can have {} or [] inside.

 

XML settings that describe the plugin.

Referring to the <Plugin> example above, notice where <Type> is Scheduler. That word may change. Scheduler means that Run happens at time intervals in milliseconds, as specified in <Interval> The other kinds (so far) besides Scheduler are Action and Filter. Action is triggered by some external action like an UpDown gesture or a button click.

At the moment, Scheduler plugins will not pile-up on top of each other. One that Runs, if it puts up an Alert, completely hangs it. This aspect needs further improvement.

Other Important functions

To make the Moose speak something, is the goal of plugins. Here's how:

Say( theString, false );
Say( theString );

2nd parameter false means normal priority. true means high priority. It's optional.

Moose.Random(min,max);

Uses C#'s random generator, which is better seeded and doesn't reset to initial seed each time a new "Run" occurs of the javascript.

Moose.Random(); // Returns 0 to 1.0
Moose.Random(mean,std,min,max); // Returns gaussian random.

element.Length;

Notice that capital L on .Length.   Javascript variables also have a .length method with lower case. What's the difference? The capital L . Length is a C# function provided by the Moose, which has the added ability of being able to tell you how many sub-elements (array elements) it is holding, And it tells you the string length when it's only holding a single string.

Plugin.RunType;

This property provided by C# into your javascript scripts, is useful inside the Run function. It has values of "Scheduler" if Run was called according to the timer settings ( interval, RunNextAt or Stream ), or "Action" if Run was called for other reasons, including: "Reload Script" menu command, Up/Down gestures and mouseclick causing Plugin.Run(); function called within an HTML view <script>.

User.GetHardwareKey();

This returns the hardward key of the windows 10 PC, which looks like a GUID, 32 chars including some dashes.

User.Firstname; User.Lastname; User.Name; User.Gender; User.Birthday; User.Address; User.Address2; User.City; User.State; User.Zipcode; User.Latitude; User.Longitude; User.Altitude; User.Email; User.Country; User.Age; User.Timezone; User.Language; User.Locale; (All of these are read-only)

 

User Interface UI of plugins using HTML

When your plugin folder contains a .html file with the same name of the plugin, it gets used, when the Open View menu is chosen. ( We will change that command name 'Open View' into something better). It will open up a window intended for editing the settings of the plugin.

In this window, you can place anything legal in HTML5, like checkboxes and buttons and text inputs.

There are a collection of Javascript and CSS files that get automatically loaded into the HTML file. Things like Bootstrap, jQuery, TweenMax, and Styles.css are intended to give the UI for moose plugins, a standard look and feature set. These automatically-loaded things are all in a folder called /Plugins/Scripts/

The rendering of HTML is using .NET WebClient. ( We're not using Chrome or Awesomium. We tried those but they weren't fast enough.)

 

Showing and editing Settings on the HTML page

For putting settings values into editable input areas on the HTML page, like textedit areas, some specific tag attributes are used. The attribute is data-setting= and in the HTML.

data-setting=

Here's an example. Suppose a Setting in the Settings.xml file was "CrossfadeDuration". The value of this would be brought into a text input using this line of code:
<input id="Crossfade" type="text" data-setting="CrossfadeDuration" style="width:45px" >

and for a checkbox,
<input type="checkbox" id="OnTheHourOnOff" data-setting="OnTheHourOnOff" >Enabled<br>

 

C# loads all the Settings at startup.

Values in Settings.xml get loaded at startup by Moose.exe, which will also automatically insert the data-setting= values into the HTML file. ( Any tag that contains the attribute data-setting= is considered to be a special parameter, whose value it intended to be used by the HTML user interface. ) C# does the first step, of reading values from the Settings.xml file, and storing them into Moose.exe properties.

Moose.exe is a C# application that is "in charge". What it thinks the values are, is supposed to be authoritative.

 

The special-ness of "data-setting="

In the Settings.xml file in a plugin's folder, here's an example of some tag values that are used for data-setting=. They look ordinary, don't they.

<Settings>
   <RootTest>False</RootTest>
   <User>
     <IsAdmin>False</IsAdmin>
   </User>
</Settings>


So even though it is cosmetic, I find it is nice to put a comment into those tags, as shown below.

And again I'll mention that the Tags.xml would need to define RootTest, User and IsAdmin, before they could be used.


<Settings>
   <RootTest Comment="data-setting">False</RootTest>
   <User>
     <IsAdmin Comment="data-setting">False</IsAdmin>
   </User>
</Settings>


In the Run function in a plugin's javascript file, you can't directly use names like RootTest and IsAdmin as variable names, not until you define them and load them with values in the usual Javascript way. I often define them as globals, and then load values into them during the Startup and Run functions.

var RootTest;
var IsAdmin;

Run = function () {
var theValue1 = Resources.Settings.GetValue("RootTest");
var theValue2 = Resources.Settings.GetValue("User", "IsAdmin");
}

 

<input>'s in the HTML user interface, using data-setting=

Here are 2 examples.

<input type="checkbox" data-setting="RootTest"> RootTest?<br>
<input type="checkbox" data-setting="User->IsAdmin">IsAdmin?<br>

Notice the -> syntax

Did you see: data-setting="user->IsAdmin" ? The -> is the syntax to step deeper into the XML structure, when using data-setting=.

 

Special formatting for Checkboxes

Just above, was an example of html code for a checkbox. That would give a fairly bland looking checkbox. To apply some fancier features, the Moose UI provides Bootstrap Toggle, and to make it work, all you have to do is add data-toggle="toggle" into the input for type=checkbox.

<input type="checkbox" data-setting="RootTest" data-toggle="toggle"> RootTest?<br>

The Bootstrap Toggle website has more documentation of ways to achieve variety of appearance of the checkboxes.

 

data-setting= GetValue and SetValue

We use data-setting=. inside of inputs like checkboxes. We can put these commands into the .html or .js files to read or set these values.

Resources.Settings.SetValue( "aValue", aValue );
Resources.Settings.GetValue( "aValue" );

So Moose.exe gets it's values updated by onchange functions from the HTML page. That's good. But it doesn't help keep the Run function () updated with changes automatically. That's a little sad I suppose.

So, there is an OnChange = function() {} entry point in our Javascript, so it can manually fetch new values from C#, whenever UI changes happen to inputs like checkboxes or text areas.

 

Plugin.RunNextAt

Plugin.RunNextAt is "undefined" when the Moose starts up, and when this is the case, then 'scheduler' type plugins are Run at intervals set by XML. So if the interval was set to 1000 milliseconds, then the Plugin would be run every 1 second. That's a lot. Sometimes you just want to have the Moose say something at a specific future time. Here's how to do it.

Plugin.RunNextAt can be only assigned the value of a Javascript Date object. But if you try to read the value, it returns a .NET date format string. Thus, it's a little tempermental.


var runNextAt = Plugin.RunNextAt;
var currentDate = new Date();
if ( runNextAt.getTime() < currentDate.getTime() ) { // do something… }

// getTime() will return number of milliseconds since 1/1/1970
// and comparing numbers is easier in JS than string comparisons, apparently.
// So the above example code will work.

// But the example below, won’t work:


if ( runNextAt == currentDate ) // do something, but this won't work.
// It will return false all the time because it’s comparing Object reference
// and not actual date value, it’s how JS works, has nothing to do with us.

This will work, below, and it's REQUIRED. It sets a future time for the plugin to Run.

// Set RunNextAt if not set already.
if ( !Plugin.RunNextAt ) {
   Plugin.RunNextAt = new Date();
}
// Add 2 minutes.
Plugin.RunNextAt = new Date(Plugin.RunNextAt.getTime() + 2 * 60000);
alert(Plugin.RunNextAt);

// Now the plugin Run function will only be called in 2 minutes from now,
// and after that, never again, unless you set a new future time into RunNextAt,
// or, change back to 'scheduler' intervals, by clearing RunNextAt.

To clear RunNextAt and resume using scheduler intervals, do this:

Plugin.RunNextAt = undefined;

Note: If you fail to change Plugin.RunNextAt to a new future time, or fail to set it to undefined, then the Moose C# will disable the whole plugin, because otherwise, times in present or past would make the plugin get called over-and-over on every main-event-loop cycle, which is a CPU massive waste. ( It must be set to current time + 1 second, or greater. Otherwise, the Plugin will be disabled.) I know it's weird. The work-around is to set RunNextAt to midnight if you don't need it right now, which will keep the plugin alive.

Note: The Plugin.RunNextAt value is not saved in a file, so it doesn't persist when the Moose is Exited and Restarted. It will be 'undefined' the next time the Moose is restarted. In other words, if you wanted it to remind you tomorrow of something, You'd have to keep the Moose running day and night.

We have plans to implement Calendar and Reminders functions, but don't use RunNextAt for that. There will be a better way.

Note: A native javascript date looks like this: "Sun, 08 May 2016 11:08:38 GMT-06:00"
A .NET date looks like this: "5/8/2016 11:25:00 AM"

If you assign a date into Plugin.RunNextAt, it must be a date object, not a string. So if you were saving a string showing a date in javascript format, you need to convert it to a date object before putting it into Plugin.RunNextAt

And it gets more ridiculous due to Javascript not always being able to know if something is a number or string or date. Look at this example code:

// I have to persuade javascript that holdthis is a string,
// not a number, by using the "" +
var holdthis = "" + Resources.Settings.GetValue("SaveRunNextAt");
SaveRunNextAt = new Date( holdthis ); // "Sun, 08 May 2016 11:08:38 GMT-06:00"
Plugin.RunNextAt = SaveRunNextAt;


If I want to store that date into a setting, I must convert it to a string, which creates local time.

holdthis = SaveRunNextAt.toString();
Resources.Settings.SetValue("SaveRunNextAt",holdthis);


You know what's also nice? Plugin.RunNextAt can be used from an HTML <script>

 

Making the Moose speak whatever this Plugin creates

Plugin.Run() is a function that is available inside of HTML pages. You can attach it to a button as an onclick= event. Here's an example, which would call the Run function of the plugin.
<button name="button" onclick="Plugin.Run()" class="btn btn-primary">Test</button>

Moose.Say( theString, thePriority); // and priority can be boolean false/true or string "Normal"/"High".

More parameters available in Moose.Say.
Pass null to use defaults.
Moose.Say(string text, PhrasePriority priority, IVoice voice, int speechRate, int volume, bool applyFilters);
// Priority true = "High",
// applyFilters true = apply the Say Name filter.
// speechRate -10 to +10
// volume 0 to 100
// voices are voice name.

Moose.IsQuiet = false; // If you set 'true' it will turn on Quiet mode and not speak.

 

Using javascript <script>'s to change moose settings, from an HTML page

Suppose you wanted a Button, that would reset some settings for the Moose, and you want that to take effect immediately. The button could call a function like: ResetNewYear(). Notice that clicking a button doesn't trigger an OnChanged event, so you have to manually set the HTML input elements, and manually set the Moose's settings values, and manually call Plugin.OnChanged(). Also notice, inside of an HTML <script> we can use Resources.Settings.SetValue() and all the other methods of Resources.Settings.


function ResetNewYear() {
   document.getElementById('HappyNewYearPhrase').value = "Happy New Year!";
   Resources.Settings.SetValue("CountDownDuration", "Happy New Year!" );
   Plugin.OnChanged();
}


Loading local files to run as javascripts, is possible, yay, but only if those files are stored in the same folder as the plugin, you can use this syntax to load them:
<script src='@file:bootstrap-timepicker.min.js'></script>.

The above example of @file: is our Moose-only extension. Normally in a web browser, you can't load local files, you can only get them from the internet. For completeness, we also have another Moose-only extension, @data: which will convert a file into a base64 string. Here's an example that loaded an SVG file.
<object id="svg" type="image/svg+xml" data="@data:images\mySVGfile.svg" ></object>

 

Entry points in our plugin javascript files

I'm aware of these 5 possible entry points, so far. The first 4 are used by plugins of type Trigger or Action, and the Filter entry point is called for plugins of type Filter. But I should check, to find out if there is any cross-over happening.

Startup = function() {

};

OnChanged = function() {

};

Run = function () {

};

Shutdown = function() {

};

Filter = function( phrase ) {
return phrase;
};

 

Settings.txt

There is a file in the en-US folder, called Setting.txt, and it contains some XML pertaining to plugins. In fact <Plugin>...</Plugin> is what holds these settings, for each plugin.

In the future, most or all of those <Plugin>...</Plugin> information should move out of Settings.txt and be put into the Settings.xml file, which is inside each plugin's folder.

<AutoSave>False</AutoSave>

This tag is about disabling the auto-saving of Settings. Normally, Values that change in Settings.xml, get saved automatically. But I'm paranoid, because there have been many occasions when I'm editing a Settings.xml as I develop a plugin's Javascript, and I make a mistake in XML syntax. So when the Moose.exe tries to load the Plugin, it encounters an error. Theoretically, if it encounters an error, it should disable the auto-saving of Settings.xml for that particular plugin. BUt what if it doesn't. What if is saves a mess of improperly loaded settings. That would wipe-out my edits, and make me mad. So if I put <AutoSave>False</AutoSave> into the Settings.txt file for that plugin, inside it's <Plugin>...</Plugin>, then it's supposed to be an extra insurance against auto-saving. I hope it works.

 

Commands for fetching webpages

 

XMLHttpRequest is available to our Javascript

It works like this:

var request = new XMLHttpRequest();     // Create Web Request.
request.onerror = OnWebRequestError;     // Provided by C#.
request.onreadystatechange = onWebRequestStateChanged;
request.friendlyName = "Google"; // Spoken word for the URL.

// Open it. ( 'true' means asynchronous, the default. false isn't supported )
request.open("GET", TestWebURL, true); // TestWebURL = "http://www.google.com/"

request.send(); // And send the request.

This method requires 1 function as callback:


function onWebRequestStateChanged() {
}


The error function callback, is provided by Moose.exe, so you don't need to include:
function OnWebRequestError() {}

 

OnWebRequestError is a built-in function for error-handling

This Error handling function, OnWebRequestError is provided by C# and is usable by all plugins, and lets the Moose speak about errors instead of showing messageBox's or Alert's. It has the feature of only speaking once per minute, even if multiple errors happen a lot faster than that. After the first minute, it progressively increases the time between speaking about errors, because it would be annoying to be interrupted by speech every minute.

This is good for users, but not good for plugin coders, because it doesn't speak about every error. So if you are a developer trying to debug a plugin, you can set your own error handling and show alerts().

OnWebRequestError is the default, so these 3 code lines are redundant:
request.onerror = OnWebRequestError;
request.ontimeout = OnWebRequestError;
request.timeout = 60000;

Another way to call OnWebRequestError, is directly in the Javascript, like a command line, like this:
OnWebRequestError.apply(this);

( Using .apply(this) gives the function the content of .friendlyName and error codes/messages )

 

XMLHttpRequest properties and methods

Here is a URL to one of the offical-looking documentation of XMLHttpRequest. https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest.

Currently usable inside the Moose's javascript plugins are these properties:

onreadystatechange
readyState
response
responseText
responseType
responseURL
status
statusText
timeout
ontimeout

- don't have upload or withCredentials
onerror ( this one isn't in the spec. It's an extra feature of the Moose. )
friendlyName ( this one isn't in the spec. It's an extra feature of the Moose. )

getAllResponseHeaders
getResponseHeader('Last-Modified')
setRequestHeader (Note, must be called after request.open )

- we don't have abort, overrideMimeType, send, or init or openRequest


 

Setting user agents

Normally it's not necessary, but if you need to change the useragent for specific web requests, this is how to do it.

request.setRequestHeader(“User-Agent”, “Talking Moose”);

 

The difference between .response and .responseText

When you use request.responseText, it is just a plain string.

When you use request.response, it can contain JSON that is ready to be used, like:
request.response.userID
request.response.message

 

Handling timeouts

There are times when your own PC might not be able to send out network requests, so a request for a URL might sit for a long time, and you'll not get an onerror. So for this situation, there's this:
// Handle timeout.
request.timeout = 2000;
request.ontimeout = function () {
   connecting = false;
};

WebSocket support

Here are the methods and attributes we support. ( see MSDN websocket documentation ).

webSocket = new WebSocket("wss://client.pushover.net/push");

webSocket.onopen
webSocket.readyState
webSocket.send()
webSocket.onmessage
webSocket.onerror
webSocket.onclose
webSocket.close()

Notes: Once you are connected to a websocket, you can test if webSocket.readyState != 1, which would indicate the the connection has been lost. Use Google to learn the readyState values.

Using APIs that return JSON

Suppose you fetched from an API using the above XMLHttpRequest.
If you set request.responseType = "json", then our Javascript will automatically
parse it and put the result into request.response;
request.responseType = "json";
 
request.onreadystatechange = function () {
if (this.response && this.response.status && this.response.status === 1) {
userKey = this.response.id;
userSecret = this.response.secret; } };

The above is showing that the returned JSON had "id" and "secret", and those values are automatically usable. Yay.

 

Content-Type, application/json

Some services with APIs, want you to set this:

request.setRequestHeader("Content-Type", "application/json" );

 

About setTimeout and setInterval

When creating <script>'s inside of HTML pages, for the control panels of plugins, the full set of javascript can be used.

However, the javascript used for the actual plugin functionality, ( where the Run() function is located), does not have everything that modern javascript does. One thing not available is the setTimout and setInterval command. But to remedy that, we provide Timers.setTimeout and Timers.setInterval.

 

Streams, aka, Channels

We have implemented a method for plugins to use "shared timing", with a goal to reduce the overload of speech if all plugins wanted to speak. There is a "Minutes Channel" that is set to speak every 10 minutes. When 3 plugins are set to use the minutes channel, only 1 gets randomly chosen to speak, every 10 minutes.

The Minutes Channel has another feature, of starting the day with an interval of 10 minutes, but gradually increasing the interval until it reaches 50 minutes by the end of the day. So as the day goes on, you hear less and less from the Moose.

Facebook is an example of a "newsfeed" that prevents users from seeing EVERYTHING from every page they've "liked", and the Moose needed a similar way to prevent "too much speaking" from becoming annoying.

Internally in our javascript code, we call this "Streams", but for users we call them "Channels" (like TV channels or radio channels).

In a plugin's .js file, these commands are available:

var theStream = Moose.FindStream("Minutes Channel");
Plugin.SetStream( theStream.Name );

There are 5 pre-set streams available. "Minutes Channel", "Hours" and 3 others, "Morning", "Afternoon" and "Evening". These values can be read or written:


theStream.Name // yes, it is the name of it.
theStream.MinInterval // in milliseconds, so 600000 is 10 minutes.
theStream.MaxInterval // 3300000 is 55 minutes.
theStream.Duration // 36000000 is 10 hours.
theStream.StartTime // if 0 or null, then 24 hours a day.
theStream.EndTime // or if StartTime in milliseconds is 10 hours past midnight, it starts at 10am.
theStream.Easing // "EaseInOutCubic" S-shaped curve, 10 hours to go from 10 to 55.
theStream.ResetTime // global value, changing for one Stream will affect them all.
theStream.NextRunTime // read-only, tells you when it will speak next.


Other kinds of easing functions available: None - linear, EaseInCirc, EaseOutCirc, EaseInOutCirc, EaseInCubic, EaseOutCubic, EaseInOutCubic, EaseInExpo, EaseOutExpo, EaseInOutExpo, EaseInQuad, EaseOutQuad, EaseInOutQuad, EaseInQuart, EaseOutQuart, EaseInOutQuart, EaseInQuint, EaseOutQuint, EaseInOutQuint, EaseInSine, EaseOutSine, EaseInOutSine

While it is possible to create other custom channels, perhaps as a means to use Easing functions for speech time intervals, we haven't documented it (yet).

Setting Plugin.SetStream( null); is the method to disable a stream. You may wish to do this because of the priority system of "When to run next".
Highest Priority is: Plugin.RunNextAt
Second Priority is: Plugin.Stream
Lowest Priority is: the "Scheduler" which calls Run() at regular intervals.

A <script> in an HTML control panel for a plugin, can use Plugin.Stream.Name to access these values and functions related to Streams.

 

To show a list of all the plugins that are currently using a particular stream:
var list = Stream.ListAllPluginsOnThisStream();

Plugin.UseStream

The command Plugin.UseStream = true; ( or false), allows a plugin to be nicely configured to use Streams, but you can set Plugin.UseStream to be false, which will prevent it from being randomly chosen. This is handy when plugins are also disabled by the main checkbox, because it prevents the Streams from giving a disabled plugin an unnecessary chance to speak, which the user would hear nothing, and it would seems like Streams were broken.

Links that open other plugins

We have this: onclick="OnMinutesChannelClicked()"
which you can put into buttons or text links, etc.

And we have

<script>
  function OnMinutesChannelClicked() {
    Moose.OpenStreamView("Minutes Channel"); // returns bool
  }
</script>


Also are these functions, which work.
Moose.OpenPluginView("MinutesChannel"); // returns bool
Moose.OpenPluginViewMinimized(viewName);

thePlugin = Moose.FindPlugin("Jokes Plugin");
theJokes.Run();

Moose.OpenWebBrowser("http://talkingmoose.ca");

Moose.ExitApplication();

 

Including other javascript code using Require

We can do this. It is restricted to only allow fetching from within the Moose folder. You can't go outside and search the whole PC.
Require("..\\Shared\\TestScript.js");

Require is for use inside the Javascript files that do Startup, OnChange, Run, Shutdown. It doesn't work in HTML files using <script>.

 

Exports, exported functions and variables

 

Exported Function

One plugin can call some code from another plugin.

  var val = Exports.Call("ExportPlugin","ExportFunctionName",param1, param2);
}

But in order for this to work, the other plugin must "Export" the function. Here's how.
function exportFunctionName(var1, var2) {
  globalVar++;
  return globalVar + var1 + var2;
}
Exports.Add(exportFunctionName);

Exported Variables

Exports.SomeValue = SomeValue;

Please note that "SomeValue" name must be unique amongst all Plugins, because all Plugins can get an exported value, using:
var theValue = Exports.GetValue('PluginName','SomeValue');

Note that both PluginName and SomeValue are in quotes. I often forget that for SomeValue

• To read values from other plugins, although it's faster to use theValue = Moose.FindPlugin('PluginName').Resources.Settings.GetValue('ValueName'); that is not recommended because Moose.FindPlugin() is not thread-safe. Another plugin might be calling the same command,
  but with a different PluginName, and you could get the value from the wrong plugin returned, which is a mysterious bad behavior.
• Using Exports is not supported in .html <script>'s. The reason is that the Exports.Call() and Exports.GetValue() are thread-safe, meaning they lock the function until it's finished. Because the .html is run from the main UI thread, we don't want it to become thread-blocked while waiting for Exports.GetValue(), while some other plugins .js files are busy using Exports.Getvalue().
• The workaround for .html files using <script>'s, is to use Events. Let the .js file call Exports.GetValue() and then sent the value to the .html file using an Event.

More notes about Exports.

• Exported variables are a COPY of the variable and have no live link to the original. Every time you change the original, you also have to copy that change into the exported variable. Every time you change the exported variable, the original is unaffected. So you have to be explicit about putting values into variables.
• Exported functions are calling the original function in it's original location. Thread locking is automatically implemented, to prevent 2 plugins from calling the same exported function at the same time.

 

Saving Plugin settings to the Cloud

Some settings are only stored on the local PC, in the Settings.xml files, which is a fine, dandy place for things to be. But when you have several computers in your life, it's nice if certain settings could stay synchronized on all your PCs, for instance, so that you don't hear the same jokes at work, and again at home.

We put 'Cloud="True"' as an attribute inside the xml tags of settings that we wish to synchronize using cloud storage. Here's an example, defining a setting in a plugin's Settinigs.xml file:

<JokesOnOff Cloud="True">True</JokesOnOff>

We're hoping to automate this, so I'm skeptical of using these commands:

In the Plugin's javascript file, in the Startup() function, you could use this code:

var cloudSettings = Plugin.GetCloudSettings();
if (cloudSettings != null) {
    cloudSettings = JSON.parse(cloudSettings);

Plugin.SyncSettings();

 

Saving User settings to the Cloud

Temporarily, ( not shown here), we have a C# function that will login to facebook, using a facebookAppId. I'm showing (not documented) instead of the real thing, because it costs me money personally to have people store settings on the cloud, charged for every time they do anything on the cloud, so I don't want users to be able to CreateSettings or do a lot of Getting or Setting or Synchronizing.

and then we can create settings using key value pairs,
(not documented).Createsetting("FirstName","Steven");

YourFirstName = (not documented).GetValue("FirstName");

(not documented).SetValue("FirstName", "Brian");

(not documented).Synchronize();

 

Adding Event handlers and sending events in Javascript

There are 2 places where javascript exists, and both can use events and event handlers.
The .html files ( in <script>'s ), and .js files.

You give an event a specific name, and provide a function that will run when the event happens.
Events.OnEvent(EventName, function );

You can trigger that event to happen using:
Events.TriggerEvent(EventName, param1);

You can pass as many parameters as the event handler function can receive:
Events.TriggerEvent(EventName, param1, param2 );

You can use Events in .js files and in a plugin's .html file. When using it from an HTML file <script>, don't try to trigger an event until the page is fully loaded.
$( window ).load( function() {
   Events.TriggerEvent("Get something");

});

If multiple different plugins create an event handler using the same EventName, then all those plugins will receive copies of the same event, whenever 1 is triggered anywhere.

The following system events, can be listened to:

• WindowActivated
• WindowDeactivated
• WindowRequestBringIntoView
• WindowGotFocus
• WindowLostFocus
• WindowStateChanged

At the moment, only WindowStateChanged is useful. The rest are unreliable.

Events.OnEvent("WindowStateChanged", function (state) {
   if ( state == "Minimized" ) {
     Moose.Say( "State Minimized" );
   } else if ( state == "Normal" ) {
     Moose.Say( "State Normal" );
   }
});

 

Thread locking

 

When an exported function is used by several plugins, those plugins Run() on separate threads, and there is a chance they could simultanously call the exported function, causing multi-threading multi-entrant problems. So the solution is to lock and unlock. Here's the code. NOPE. THis is obsolete.

var lock = new ThreadLock();
Exports.threadLockTest = function (param) {
  lock.enter();
  alert(param);
  lock.exit();
};

We're using something different now. Exports.Call("Library","functionname");

 

<include>

 

<include src="@file:..\\Library\\Timing.html"></include>

This is very handy, for putting some common UI elements in just one file, and letting all other plugins include that html code.

 

Timers

 

Although javascript in .html files in <script> can use the setTimeout and setInterval commands, those are not available in the .js files of plugins. But there is a similar alternative, usable only in the plugin.js files:
if (timeout === null) {
  timeout = Timers.setTimeout(function () {
    alert("Timeout");
     timeout = null;
  }, 1000);
}
if (canceledTimeout === null) {
  canceledTimeout = Timers.setTimeout(function () {
    // If interval is running it will cancel this timeout.
     alert("canceledTimeout");
    canceledTimeout = null;
  }, 10000);
}
if (interval === null) {
  interval = Timers.setInterval(function () {
    // Cancel canceledTimeout.
    if (canceledTimeout !== null) {
    Timers.clearTimeout(canceledTimeout);
    }
    alert("Interval");
  }, 5000);
} else {
   // Run again to cancel interval.
  Timers.clearInterval(interval);
  interval = null;
}

The above code is complex. It can be a simple as this:
Timers.setTimeout( function() { alert('hi'); }, 1000 );

 

OpenPluginView with Parameters

 

The <script> inside a .html plugin view, can use a special entrypoint called:

OnOpen = function (any arguments you want here) {
// Whatever code.
};

And any plugin.js or any other plugin.html can open that plugin view with

Moose.OpenPluginView("PLUGIN NAME HERE", [arguments here]).

OnOpen is called every time a .html plugin is opened. It is called AFTER $(window).load is finished.

 

Security functions

 

theHash = Security.Hash(theString,64); will create a hash of a string, which is safe to store in Settings.xml, and useful for comparing to find if something changes later in time.

theCrypted = Security.Encrypt(thePhrase,EncryptPassPhrase);
thePhrase = Security.Decrypt(theCrypted ,EncryptPassPhrase);