JavaScript feature

MINI LESSONS ›› Actions Editor ››

MINI LESSON

ADDING JAVASCRIPT TO YOUR PROJECT

With this feature 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.


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 walk through 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;

}

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 Publish to Web 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_.

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, you'll need to write your 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. Generally putting the code in the book script is the best idea. Below is the same logic written in OpenScript.


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 OpenScript function is also prefixed by tbfunction_, and also allows for one parameter named number.

Using the new function

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 our 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. You can get into the editor by double-clicking on the 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 an indication that ToolBook is able to successfully locate a JavaScript function named tbfunction_addComma in the .JS 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 the function does its work it optionally 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.



KEYWORDS: 20568 P833




Created with the Personal Edition of HelpNDoc: Free help authoring tool