Creating Plugins

To 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.

Just so you know, our Settings.xml, is a security feature. Normally Javascript can’t save files on your local computer, and Plugins aren’t allowed to change your computer either.

But we allow your plugin data to be stored in this one file: Settings.xml, which is safe. That’s why we’re discussing using Settings next.

The GetSetting() and GetAllSettings() functions

In the GetSetting() function, the parameter is a Tag name (the name of a setting)(optionally preceded by a path ).

GetSetting() can have a single parameter name 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.

I rarely use this. But further below, I use GetValue() a lot.

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 It’s Friday. is holding only a value (a string). GetSetting does work when there are nested settings-Groups inside it.

I hardly ever@file use nested settings. But if you need them, this lets you work that way.

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, of looping through a group of settings.

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…);


Random and Shuffled

One extra function is GetRandomSetting(path) that will pick one value 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.

Settings.xml is a good place to store strings intended to be spoken by the Moose, because Random and Shuffled spoken sentences, is a nice automatic feature for users.

Resources.Settings.GetLength("Jokes","String");

Resources.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.

I use Resources.Settings.GetValue('Something');
all the time.

The GetValue() and GetAllValues() functions

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

All settings are Strings.
So sometimes you have to manually convert them to numbers.

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


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

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.

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”);

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”);

That's crazy! Just look at how that steps deeply into nested data, and the final parameter sets the value.

I just try to avoid nested settings, they seem complicated.

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

Resources.Settings.Remove(path); is available. Useful only in OnUpdate entry point.

Resources.Settings.SetValue("DoesntExist","whatever"); is actually capable of creating a setting that doesn't yet exist.

We don't yet have Rename, or Copy implemented in javascript for settings.

The automatic updates process sometimes needs to completely replace a settings file on a users PC. This is only for BIG changes, and it would wipe out the user's chosen values, which is not good. So try to preserve those by saving the important ones into temporary vars, and setting them again after calling ReplaceSettings.

Resources.ReplaceSettings("NewSettings106.xml", true);

It will return true or false and second parameter is a flag if you want to delete the file when done or not.

Generally this is only used from inside of an OnUpdate() function.

Use Resources.Settings.GetValue() in javascript and in HTML

Repeat: You can GetValue() in Javascript and in HTML.

Why did you tell me this?

It's one way for your .js file to communicate to your .html file.

Another way to send data, is using Events.

Settings.xml is a text file.

Settings.xml is an XML format file. Use any tags you want. Edit in a text editor.

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.

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.

The Moose's core 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.

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>


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

<Settings>
   <RootTest Comment="Reminds me of root beer">False</RootTest>
   <User>
     <IsAdmin Comment="Did you give yourself powers">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. (see example below.) I often define them as globals, and then load values into them during the Startup function.

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

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

Here are 2 examples of inputs. (Areas to type in some text.)

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

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=.

I have a confession. I rarely use this -> method, I rarely use nested settings.

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">

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

GetValue and SetValue and data-setting=

These 3 important commands, are all used on your settings data.

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 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.

Half temper, half mental.

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

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 won't work.

But this won't work (above). It will return false all the time because it is comparing an Object reference, and not an actual date value.

Why tell us things that don't work?

I keep forgetting, and making the same mistake. I refer to these notes, for myself.

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.

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>, if you want to display it's value.

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

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 or
upload or withCredentials

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" );

Warning. API servers are unpredictably fickle. Sometimes, including this header will prevent it from working, even though you are absolutely sure that you are supposed to send json. Other times, you do have to include it.

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.

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.