Version: 1.0.0
The Project Web App in
Alpha WatchBenchTM


Commands
The Project Web App

Each WatchBench project has an "index.html" file. Whenever you switch to a different project, this file is loaded into a web view and displayed in Window 2. While called a "web app", it is loaded locally and not from the web. It is, though, similar to a normal, single-page web app. It can react to events, such as taps on buttons, and execute JavaScript to change what it displays, make Ajax calls to a server, or have an effect on other parts of the WatchBench app.

The Project Web App may be used to display simple documentation about a project, to provide a means for setting values used by the project, to provide a means for the JavaScript connected to the watch to display information on the screen, or it may be ignored completely.

Each time the Project Web App is loaded, its environment is reset, just like when a normal web page is reloaded. Reloading occurs when the "Run index.html" item is chosen in the list of files for Window 2, and when the Reload button in the upper-right corner of the header is tapped when the Project Web App is being displayed. The Project Web App can refer to other files in the project, including the "main.css" file that is created by default for a new project.

WatchBench provides special "awbexecute:" functionality to enable the Project Web App to communicate with the rest of the app. It is described in detail below.

In addition to "awbexecute:", the "browser:" URL scheme will cause the URI-encoded text that follows to be passed to the iOS "Open In" API. This lets you, for example, launch a normal browser session for additional help information, etc.

The Project Web App is run as part of the iPhone WatchBench app that runs like a normal app on the iPhone. Except through its special "awbexecute:" functionality, it has no connection to what actually runs on the watch. The watch does not display HTML, etc.

The watch JS can access and have effect in the running index.html Project Web App using the AWBlib.appCmd function. For example, you may wish to have a more detailed list of downloaded data displayed on the iPhone than on the watch screen if the user viewed the iPhone after retrieving data with the watch.

Top of Page
AWBEXECUTE:
When the Project Web App is running, it behaves like a normal HTML page. However, attempts to load from certain URLs are treated specially.

The most important special URL is "awbexecute:". This is a URL scheme that is reserved for communicating with WatchBench.

If the following is executed:
document.location = "awbexecute:";
WatchBench will execute certain commands that the JavaScript in your Project Web App specifies. Those commands are fetched from a JavaScript top-level object, AWBcmds, that must be defined in the Project Web App running environment.

The AWBcmds object must be an array. Each element in the array must be another array object. Those arrays, in turn, consist of a string as the first element indicating the command to execute, followed by other arguments as required for the command.

The general form of AWBcmds is:
[["cmd1",arg1,arg2,...],["cmd2",arg1,...],...]
The execution of the commands does not start until after the Project Web App JavaScript returns from an event, such as "onclick". While only one "awbexecute:" sequence may occur in response to an event (that is, you may not set document.location multiple times and expect separate executions), the AWBcmds object allows for the specification of multiple commands to be executed in sequence.

Here is an example of using this functionality to write a string to a file when a DIV is tapped:
<script>
var AWBcmds = [ ];
function save(str) {
AWBcmds = [["writeFile","a.txt",str]];
document.location = "awbexecute:";
}
</script>
...
<div onclick="save('One');" ... >
One of the commands that may be used is the "eval" command. This causes the argument to be taken as a string and executed in the Project Web App environment. This, for example, makes it easier to make use of data retrieved by reading a file.

For example:
<script>
var AWBcmds = [ ];
var statusv; function getstatus() {
AWBcmds = [["status","statusv"],["eval","alert(JSON.stringify(statusv))"]];
document.location = "awbexecute:";
}
</script>
...
<div onclick="getstatus();" ... >
log
Add text to currentAppLog.txt
["log",stringval]
Adds stringval to the currentAppLog.txt file for the project. Note: This is the App log, not the Watch or Glance log.
For example:
AWBcmds = [["log","Button tapped."]];
alert
Displays an iOS-style alert
["alert",title,msg]
This function shows an app alert with the title of the string value of title and the message of msg.

This is different than the JavaScript window.alert() function.
insert
Adds text to file being edited
["insert",stringval]
This command inserts the specified string value at the insertion point in Window 1 if it is editing a file.

For example:
<script>
var AWBcmds = [ ];
function insert(txt) {
AWBcmds = [["insert",txt]];
document.location = "awbexecute:";
}
</script>
...
<div onclick="insert('My boilerplate...');" ... >
readFile
Retrieves contents of file
["readFile",filename,varname]
This command reads the text file specified by the string value of filename and stores the contents as a string in the variable named by the string varname.

For example:
<script>
var AWBcmds = [ ];
var settings = "";
function read() {
AWBcmds = [["readFile","a.txt","settings"]];
document.location = "awbexecute:";
}
</script>
...
<div onclick="read();" ... >
readFileBase64
Retrieves contents of data file
["readFileBase64",filename,varname]
This command is the same as the readFile command, except that it reads the file as 8-bit bytes and encodes the data using Base64-encoding and stores that encoded data as a string.
writeFile
Writes text to file
["writeFile",filename,stringval]
This command writes the value of stringval to the file specified by the string value of filename.
writeFileBase64
Writes Base64 data to file
["writeFileBase64",filename,stringval]
This command converts the stringval from Base64 data encoding to raw 8-bit byte data, and then writes that raw data to the file specified by the string value of filename.

The HTML <canvas> element may be used to create images and then the data from that image may be retrieved as Base64-encoded data. This makes it easier to use that data and write it out as a normal image file.
deleteFile
Deletes a file
["deleteFile",filename]
This command delete the file specified by the variable named by the string varname. This command has access to all of the project's files, so use it with care.
eval
Evaluates JavaScript
["eval",stringval]
This causes the stringval to be executed in the Project Web App environment. It is useful as an additional command in the AWBcmds array to be executed after other commands. This is because the AWBcmds are all executed at a time not synchronous with the setting of document.location.

See the example in the description of AWBEXECUTE: above.
status
Retrieves app status
["status",varname]
This command sets the object specified by the varname string to the following:
{
version: "Full WatchBench version",
shortVersion: "Shorter version",
screenwidth: width-as-number,
screenheight: height-as-number,
stateString: "value of stateString"
}
Note that the screenwidth, screenheight, and stateString are read from the currentWatchState.txt file. That file may not exist or be initialized and the values may be 0, 0, and "", respectively.
Top of Page