ToolBookHelp.com - About the JavaScript feature in TB 2004

ADDITION OF JAVASCRIPT IN TOOLBOOK 2004

Okay, so you can now add your own JavaScript in your ToolBook applications. What exactly does this mean?

The first thought I'm sure you have is: Cool, ToolBook can run JavaScript. But you'd be wrong. ToolBook is not able to execute any JavaScript.

What this really means is that you can incorporate JavaScript functions into your Actions Editor programming, and when you export to DHTML, the JavaScript functionality (which works fine in a browser environment) will work.

Okay, what about Before you export to DHTML, what happens when you try to call the function in native ToolBook via the Actions Editor? Well, the function will fail to process at all, unless you supply an OpenScript version of that function.

The best way to explain this is to show you. So look at the walkthrough below to see what this is all about.

Writing or borrowing someone's useful JavaScript function
For this example I searched the vast world of the Internet looking for JavaScript libraries (free of course) and found the following one to work with in order to show you this example. This function will take a raw number such as 1234567 and change it into 1,234,567. Note that this function is not a very well written function as it will convert 1234.12 to 1,234,.12. This is a good lesson however, as it demonstrates that if you borrow someone's logic, it is only as good as the programmer who wrote it.

function addComma(number) {
number = '' + number;
if (number.length > 3) {
var mod = number.length % 3;
var output = (mod > 0 ? (number.substring(0,mod)) : '');
for (i=0 ; i < Math.floor(number.length / 3); i++) {
   if ((mod == 0) && (i == 0))
    output += number.substring(mod+ 3 * i, mod + 3 * i + 3);
   else
    output+= ',' + number.substring(mod + 3 * i, mod + 3 * i + 3);
}
return (output);
}
else return number;
}

As I don't know the first thing (or second thing) about JavaScript, I can't tell you exactly how the code works, but it actually is quite readable from a generic programming standpoint. I'm just glad someone else wrote it.
Modifying the function name to agree with ToolBook's requirements
It is a requirement to rename your JavaScript functions by prefixing them with tbfunction_. So in the above example the function declaration line would be written as:

function tbfunction_addComma(number) {
Putting the JavaScript function into a .JS file
In order for ToolBook to be able to use your JavaScript function you will need to put it inside of a .JS file.

What is a .JS file? Well it is just a library of JavaScript functions. You can add dozens of different JavaScript functions into a single .JS file and then only have to keep track of this one file.

For the purposes of this example you will need to open Notepad, add the JavaScript code to it, and save it as something such as addcomma.js. Yes it is that easy to create a .JS file.
Importing the .JS file into ToolBook
Before doing this I would suggest dropping the .JS file into the same directory as your .TBK file, so that ToolBook can locate it easily when ToolBook starts exporting your book. Yes, this means that the stuff in the JS file in not really sucked into the .TBK file, the file itself is simply pointed to, and when the export to DHTML process occurs, the .JS file is copied into the export folder.

To import the .JS file so that you can use the functions within it, use the IMPORT button on the WEB tab of the Properties for Book dialog. Once you import it, you can click on the Functions radio button to see a list of functions found in that .JS file you just imported. Note that it will only show you the functions which are prefixed with tbfunction_. You can see in my screenshot that I imported the addcomma.js file and that the only function found in it is addComma, and that function has one parameter named number.

NOTE
Although you prefixed the function name with tbfunction_, ToolBook will never show you the tbfunction_ portion within ToolBook itself. It uses the tbfunction_ portion only for internal purposes.
Adding an OpenScript version of this functionality
Because you'd likely want the functionality of the JavaScript to work in ToolBook before you export so that you can test your application, I needed to write my own OpenScript version of this same functionality.

The function can be placed anywhere in the .TBK file as long is it is higher up in the hierarchy than the object calling the function. In my case I decided to put the function in the Book Script. Below is that script which I wrote. Note that my code is smaller (oh the power of OpenScript), but also notice my code suffers the same flaw I talked about earlier which was found in the JavaScript code. I wanted to keep both functions working identically to each other.

to get tbfunction_addComma number
ct = charCount(number)
if ct > 3
    step k from (ct - 2) to 2 by -3
      char k of number = "," & char k of number
    end
end
return number
end

Notice that the function I wrote in OpenScript is also prefixed by tbfunction_, and also allows for one parameter named number.
Using the newly imported function (and newly written function) in the Actions Editor
Now that the function has been imported into ToolBook, the Actions Editor will now be aware of this function and permit us to use it.

To test this, lets say my goal is to have the user type in a number, and then have ToolBook display it with the commas in place when the user clicks a button.

The following code does just that. Notice that a new Execute Script feature is found in the General category.

To fully configure the Execute Script action, you will need to access the editor for this action. From the condition shown in the screenshot above you can get into the editor by double-clicking on the Scroll Icon at the beginning of the line of code. Doing so would reveal:

Notice that I have chosen the addComma function from the combobox, as the function I wish to call. For those wondering, the (HTML & Native) text you see following the function name is a indication that ToolBook is able to successfully locate a JavaScript function named tbfunction_addComma in the .JS imported files as well as an OpenScript function named tbfunction_addComma somewhere in the object hierarchy. If you forgot to include the OpenScript version (or it is not properly located in the hierarchy), then only HTML will appear in the brackets.

Parameters: You will see that "number" is specified as a Parameter. This is read from the .JS file when the function was imported. This way you know what the names of the parameters are and how many of them need to be passed to the function. In my case I set the value to the data contained within the field named source which is on my ToolBook page.

Return Value: When function does its work and passes back an answer you will need to specify a variable to accept the returned value.

You're finished, that's it. Now when you test this in Native ToolBook the OpenScript function will return the correct answer, and when exported to DHTML, the .JS file will be used to provide the JavaScript function which permits this to work in DHTML too.