Panels Plugin - Beta

[Gary]

Well, here it is.  It's my first stab at this thing and I'm very curious as to what folks will do with it o_O  There are a LOT of words in here, but at the end of it all, you'll see it's not as complicated as it seems.  All the current notes are below as well as within the .zip itself.  The plugin will be attached here and is available from the site:  https://www.voiceattack.com/filesend.aspx?id=panels_beta.zip

Here is the goofy demo video that I did a little while back that goes with this: 
https://www.youtube.com/watch?v=7I2Rel3lYuw   The included demo is more like the third panel shown with a little bit more added to it.

Have fun and Merry Christmas :)


Panels plugin

I was wanting a way to control VoiceAttack's macros by a remote device for various (fun and not so fun) reasons.  I didn't have the resources to spend building an actual app to run on an iPad or Android tablet mostly because I wanted VoiceAttack users (including myself) to be able to create and share game and app screens relatively easily (and quickly).  Since practically every touch device now has some sort of built-in web browser and loads of folks can understand and write (quite fantastically, actually) HTML and JavaScript, it was not a stretch resolving to use this common, multi-platform interface.

The Panels plugin is NOT IIS or Apache lol.  It is very basic in what it does, which is serve up HTML, CSS, JavaScript and some binary assets (sounds and images), plus it is wired to respond to a very small VoiceAttack JavaScript object called (strangely enough), 'Panels'.
 
The plugin has a very small number of configuration options that should take care of most needs, however, this is (hopefully) going to be an ongoing project, so we can all figure out what is needed together down the road.

Note:
I wanted to get this out there for everyone, so this documentation is probably going to have a lot of holes in it.  There is going to be a lot of reliance on the, 'demo' panel that is included to explain what is going on (there are some additional notes that come with the demo).


Installing the Panels plugin

Panels is a plugin for VoiceAttack, so it has to be properly installed in order to work.  To install the plugin, simply copy the ENTIRE folder (called, 'Panels') from the .zip into the Apps directory that is in your VoiceAttack installation directory (unless you moved the Apps folder). 

Next, make sure that you have the, 'Enable plugin support' checkbox checked inside Options screen of VoiceAttack.  If everything is done right, you'll see, 'Panels plugin initialized' (or something similar) the next time you run VoiceAttack.  Included with the plugin is a sample profile called, 'Panels Demo - Profile.vap'.  Just import this profile and you will see a collection of commands that will be used as part of the Panels demonstration.

Note: The first time you run the plugin, you will get a Windows Security Alert box that says, 'Windows Firewall has blocked some features of this app'.  This is good, but you will need to allow access to the plugin or you may get met with this box every time the plugin is loaded.


Configuring the plugin

The Panels plugin has a very small and light web server built into it.  Panels should work straight away for most people, as it is configured by default to listen across all ip addresses on port 80.  It is also configured to not block any addresses, as well as default to the Demo folder that comes with the .zip.  In case you need to change up these settings (which you probably will at some point), simply go into the Panels folder and edit the, 'panelsconfig.txt' file.  Inside this file, you will find a handful of settings, outlined below.  Note that the settings are formatted as, 'setting_name:setting_value', with the colon in the middle.

port:port_number - This is the port number for Panels to listen for requests on.  The initial value you'll find is, 'port:80', which means that Panels is listening on port 80.

ipaddress:ip_address - This is the ip address that Panels will listen for requests on.  The initial value you'll find is, 'ipaddress:0.0.0.0', which means Panels will listen on any address.

defaultfolder:folder_name - This is the default folder that Panels will use if you browse to it and do not include a folder name (see, 'Browse to your, 'panels'' below).  If you specify no folder, Panels will browse to a screen that lists your folders.  The initial value is, 'defaultfolder:demo', which tells Panels to go to the, 'demo' folder (if no folder is specified).

whitelist:ip_addresses - This is an ip address white-list (device ip addresses that are allowed to access Panels).  You can white-list client ip addresses if you have housemates that like to mess with your setup.  Just indicate all addresses to white-list separated by a semicolon (;).  You can also indicate simple ranges with addresses separated with a dash (-).  Examples:

If you want to just include one address to white-list (in this example, single ip address, '192.168.1.10'), indicate like this:

Code: [Select]

whitelist:192.168.1.10
If you want to specify a simple range of addresses (from 192.168.1.1 through 192.168.1.10):

Code: [Select]

whitelist:192.168.1.1-192.168.1.10*note the dash (-)

To specify two ip addresses, a range and another ip address:

Code: [Select]

whitelist:192.168.1.10;192.168.100.5;192.168.1.15-192.168.1.20;127.0.0.1*note the semicolons


The initial value is, 'whitelist:0.0.0.0'.  This indicates that all ip addresses are white-listed (all allowed, none are blocked). 

Hint: if you want to see what the ip address is of a device you are trying to connect, set the white-list to 1.1.1.1 and then try to connect.  The error message in the VoiceAttack log will show the address that has been blocked.



Start/Stop the plugin service

The Panels plugin can be started and stopped from a command that uses an, 'Execute an external plugin function' action.  The Panels Demo profile that you imported will have the commands to start and stop the plugin's service.  You'll notice that the command called, 'start panels' contains a single action which is, 'Execute an external plugin function'.  This action has a simple context of, 'start'.  Note that you can add this command (or similar) to your profile startup if you want the Panels service to start with your profile.  The contexts that can be used are outlined here:

start - As indicated above, starts the Panels service.

stop - This context stops the Panels service.

status - A simple status written to the log to show if the service is running or not.

demo - This will launch a default web browser using the loopback address of 127.0.0.1.  The default folder will be used (see, 'Configure the Panels plugin' above).


Browse to your, 'panels'

A Panels, 'panel' is simply a web page.  You can view your panel by browsing to its location (folder).  This is probably the trickiest part of using Panels, as there are several ways to do this and, depending on your system, may require additional configuration (due to firewall or other application/security-related system configurations).  We're not going into how to configure a firewall here, as that's an entirely rich and wonderful universe you can hand off to your teenager.  If you *do* end up needing to configure your firewall to allow traffic to Panels, be mindful of the configuration settings you set up (see, 'Configure the Panels plugin' above).

There are three pieces of information you will need to know in order to browse to your panel.  First, from your browser on a device that is probably located on your home/local network, you will need to start your address with, 'http://' (just like going to a regular web page).
 
Next, you will either need to know the machine name or the ip address of the computer that has VoiceAttack and the Panels plugin running.  So, for instance, if your computer's name is, 'Alien' and it is accessible over your network, you can type, 'http://Alien' into the browser's address bar OR you can type, 'http://192.168.1.10' if you are going to access by ip address (note that your ip address will not be the same as mine).

The third piece is going to be the panel folder.  If your folder is called, 'Elite', add, 'Elite' to your address:  http://Alien/Elite -or- http://192.168.1.10/Elite
Note that you can have multiple folders, each with their own panel.  Also, as indicated previously, you can specify a default panel folder.  If you specify a default folder, you only have to type in http://Alien -or- http://192.168.1.10 and Panels will go to the indicated folder (see, 'Configure the Panels plugin' above).

Note: If you happen to change the port number in your configuration, you will need to add the port number to your address.  So, for instance if you change your port number to 8081, your address will need to look like this:  http://Alien:8081/Elite -or- http://192.168.1.10:8081/Elite.

Advanced user note:  The name of the web page file that Panels will access will always be called, 'panel.htm' by default.  Panel.htm will reside in a folder (that you can name) that must be inside the Panels plugin folder.  If you need to browse to another page within the folder, just indicate it in the address bar directly.


So in recap and as an example (using an iPad):

First, figure out the accessible ip address or machine name where VoiceAttack and Panels are running (there are lots of resources on the web regarding how to get your local ip address if you need it). In this example, the machine name is, 'MonsterBox'.

Open up Safari.  In the address bar, type:

Code: [Select]

http://MonsterBox
Click, 'Go'.

Since the default folder is, 'demo', Panels will take you to the Demo panel.

That's all there is to that ;)


Notes:

• The demo panel will require an HTML 5-compatible browser, and uses touch events (mouse clicks will not work in a Windows browser).
• You can have as many panels, 'running' as you have resources to support them.
• Firefox has been a little problematic when serving up scripts, css and assets.  You may need to serve scripts, css and assets from your own site if you want to support Firefox.
• Microsoft Edge will not browse on a local machine with the ip address.  This is by design.  Instead, to test using Edge, use the loopback address of 127.0.0.1
• Other applications may occupy a particular ip/port when running.  You'll get a message in the log about it.  Just change your configuration as necessary (or kill the offending app... *cough* Skype on port 80 *cough*...).
• Bookmark your addresses for easy access.  If using Safari on an iPad, you can go full screen by adding your bookmark to the home screen (note that there is a meta tag to add to your page and you'll find it near the top of the demo panel source).  Going full screen with Chrome on an iPad requires you to swipe the page from the bottom up a ways until it goes full screen...  this works until you slide down a little (bleh).

Creating your own panels

This is going to be the hard part, I'm afraid.  Unless you get your panels from somebody else, you will need to create your own panels to interact with the Panels plugin and VoiceAttack.  The good news is that a panel is simply HTML with a touch of JavaScript.  From there, how elaborate you want to get is all up to you.

To keep things simple, for each, 'panel', you create a folder that is IN the same folder as the Panels plugin.  If you browse into the Panels plugin folder (probably C:\Program Files (x86)\VoiceAttack\Apps\Panels), you'll notice there is already a folder in there called, 'demo'.  'Demo' will be the name of the panel.  When browsing to that panel, you would just use the address, 'http://someComputerAddress/demo'.

If you create a folder called , 'myPanel', you would use the address, 'http://someComputerAddress/myPanel' .  Hope that's clear o_O

From here, the assumption is that you have some level of HTML/JavaScript knowledge.

Inside your panel folder is where you will store a file named, 'panel.htm'.  'Panel.htm' is the default panel name.  The plugin will find this file automatically and serve it up when you browse to the folder.  You'll notice inside the, 'demo' folder, that there is a, 'panel.htm', as well as some other folders.  These folders are NOT necessary, but are used to keep things organized.  If you edit the, 'panel.htm' file, you'll notice that the paths within the file are relative to those subfolders.  Again, your scripts/css/assets don't have to reside in these folders, they can reside in the same folder as, 'panel.htm' (or even linked from your own site), just as long as the paths to the scripts/css/assets are correct.

Within the, 'panel.htm' file, you MUST include a reference to two scripts in order to interact with the Panels plugin. The first script is called, 'vaPanels.js' and the second is a jQuery script called, 'jquery.min.js'.  Both of these reside in the scripts folder for the demo panel.  You can see how these are linked in within the, 'panels.htm' file.

Accessing the Panels plugin from your, 'panel' is done through the, 'Panels' JavaScript object (it gets included with the vaPanels.js script).  There are just a few functions that go along with the Panels JavaScript object.  You access the functions by using the, 'Panels' object like this:  Panels.execCommand(...) or Panels.getText(...). 

Here is a list of all of the Panels object's functions:

Panels.execCommand(commandName, waitForVA, doneFunction, failFunction, doneFunctionTag) - Executes a VoiceAttack command. This is optionally an asynchronous function (see parameters below).

commandName - string (required)- This indicates the exact name of the VoiceAttack command to execute.  This is the only *required* parameter for this function.  For most purposes, this is all you may need.

waitForVA - boolean (defaults to false if not included) - This instructs the Panels plugin to wait for VA's command to finish before responding to your panel.  So, if you have a command that may run for a bit and, say, sets a variable you will need, this option will be handy.

doneFunction - function (defaults to null if not included) - This is a callback function that accepts a single string parameter.  Including this parameter will instruct execCommand to run asynchronously.

failFunction - function (defaults to null if not included) - This is a callback function that accepts two parameters: jqXHR (error object) and exception (which is a string).

doneFunctionTag - string (defaults to null if not included) - This is a simple tag that you define that will be returned as the tagMessage in the doneFunction callback (can be used to consolidate callback functions and/or distinguish callbacks).

Note: Excluding BOTH the doneFunction and failFunction parameters will instruct execCommand to run synchronously.

This example simply calls the, 'fire weapons' command and doesn't have the plugin wait or indicate callback functions:

Code: [Select]

Panels.execCommand('fire weapons');

This example again calls the, 'fire weapons' VoiceAttack command, but does not continue until the VoiceAttack command has finished and the plugin has responded:

Code: [Select]

Panels.execCommand('fire weapons', true);

This example calls the, 'fire weapon' command and tells the plugin to wait until VoiceAttack is finished processing before responding.  We've also included the, 'myCallbackFunction' function that will be called when the plugin does respond (and also indicates that the function is to run asynchronously).  'myFailFunction' is the function that will be called if there is an error in transmission, and 'my special tag' is a value that you define which is sent back and passed to, 'myCallbackFunction':

Code: [Select]

Panels.execCommand('fire weapons', true, myCallbackFunction, myFailFunction, 'my special tag');

function myCallbackFunction(tagMsg)
{
    alert(tagMsg);  //this will show a message box that says, 'my special tag'
}

function myFailFunction(jqHXR, msg)
{
    alert(msg);
}

Panels.getText(variableName) - Gets the value of a text variable contained in VoiceAttack.  The value can be null.  This is a synchronous function.
variableName - string (required) - indicate the variable name you want to retrieve (including scoped variables).

Panels.setText(variableName, textValue) - Sets the value of a text variable contained in VoiceAttack.  The value can be null.  This is a synchronous function.
variableName - string (required) - indicate the variable name you want to set (including scoped variables).
textValue - string (required) - the value you want to set to the indicated variable (again, this can be null).

The rest of the functions are just like the ones above, just for different types:
Panels.getBoolean(variableName)
Panels.setBoolean(variableName, booleanValue)

Panels.getInt(variableName)
Panels.setInt(variableName, intValue)

Panels.getSmallInt(variableName)
Panels.setSmallInt(variableName, smallIntValue)

Panels.getDecimal(variableName)
Panels.setDecimal(variableName, decimalValue)

Panels.getDate(variableName)
Panels.setDate(variableName, dateValue)


So, in short, it's just one function to execute commands and 12 functions that get and set data types.  That's all you have to worry about (for now lol).  Hopefully, the demo panel gives you enough info to get you started.


Update Nov 14, 2018 - Updated Panels.dll to correct an issue where text variables were being lower-cased.