This chapter is from the book
This chapter is from the book
This chapter is from the book
Delays and Timeouts
- GoLive has a global timer that you can use to schedule execution of your own scriptlets.
- You can set a JavaScript timeout value to avoid an infinite loop or other failure in an extension’s JavaScript code that could otherwise halt GoLive indefinitely.
- You can display a progress bar or busy bar to the user while your extension performs lengthy processing tasks.
Timed tasks
You can evaluate a JavaScript expression after a specified delay. The startTimer global function accepts a scriptlet and a timeout. The scriptlet is stored internally and executed as soon as the timeout has elapsed. Optionally, the scriptlet can be scheduled for repeated execution. For example, you might schedule a script to run once per second.
The following code prints a counter in the JavaScript Output window every second:
counter = 0; myTimer = startTimer ("writeln (++counter)",
1000, true);
Note that the startTimer method’s return value is required to stop this code’s execution. To do so, pass this value to the stopTimer method, as the following statement does.
stopTimer (myTimer);
Setting the JavaScript timeout
You can specify the amount of time GoLive waits for JavaScript code to return control before it exits the current script unconditionally. Without this feature, an infinite loop or other failure in an extension’s JavaScript code could halt GoLive indefinitely.
By default, GoLive waits forever for a JavaScript function call to complete. If you are not confident that a JavaScript function can complete its task in a reasonable amount of time, you might prefer to specify the amount of time GoLive waits for a response. Each extension can specify its own timeout that GoLive uses to execute that extension’s scripts.
To set the script execution timeout, your extension’s Main.html file must include a <jsxmodule> tag (page 321) that provides a timeout attribute. The value of this attribute is the number of seconds GoLive waits for a script to return control before it exits the script. Values of 0 or false restore the default behavior of never timing out.
<html>
<body>
// give scripts ten seconds to complete before
unconditional exit
<jsxmodule timeout=10>
// scripts and SDK tags go here
</body>
</html>
Progress bars
To provide user feedback during lengthy operations, your extension can display a progress bar dialog or busy bar dialog. You can specify the title and the text to be shown while processing. For example:
app.startProgress( 'Please wait', 'Progress: 0%', false); //show bar app.setProgress(0,6, 'Progress: 60%');//update periodically
)
A busy bar does not display a progress value; instead, it rotates the spiral indicator about once a second. For example:
app.startProgress( 'Please wait', 'Processing', true); //busy bar
)
These are the same dialogs GoLive displays as part of its own user interface. Three methods of the app Object (page 53) make these dialogs available to extensions:
- The startProgress method (page 61) initializes and displays the progress dialog.
- The setProgress method (page 60) updates the status bar or busy bar display.
- The stopProgress method (page 61) hides the progress dialog.
As an alternative to these globally available predefined dialogs, you can define a progress-bar control in your own window.
Starting a progress or busy bar
The startProgress method has this syntax:
app.startProgress (title [, message, doBusy, seconds])
- You must specify the string that appears in the progress window’s title bar, such as "Please wait" in the examples.
- The optional message argument provides the initial status message displayed when the dialog opens.
- The method opens a progress bar, unless you pass true for the optional doBusy argument.
- The optional seconds argument is a number of seconds to delay before Golive displays the dialog. For example, a value of 2 means that GoLive displays the dialog only for operations that take more than 2 seconds to complete.
Updating a progress or busy bar
While the progress window is displayed, your code must update the position of the progress bar. It can optionally update the message text as well. Your code must also determine whether the user clicked the Stop button and act accordingly to abort the operation in progress. To perform these tasks, call the setProgress method periodically:
setProgress( value, [message])
- The value argument is a value between 0 and 1 that specifies the portion of the progress bar to be drawn. For example, the value .50 specifies that 50 percent of the progress bar is drawn to indicate a task half completed.
- The optional message argument is the string to display as the new status message. You can update a busy bar with a new status message; it ignores the value argument.
The setProgress method returns false when the user clicks Stop in the dialog. Your code should respond to this condition by aborting the operation that is in progress and closing the dialog. During lengthy operations, it is especially important to call the setProgress method regularly, so that your extension can respond quickly if the user clicks Stop.
When the lengthy operation is completed (or the user clicks Stop), call the stopProgress method to close the dialog.
Progress bar example
This example displays a progress bar. The doSomeWork function is your own code that performs the task on which you are reporting progress.
function progressDemo() {
var percentDone = 0;
var continue = true;
app.startProgress("Progress Demo", "Starting, please
wait.", busy);
while (continue && percentDone < 100) {
doSomeWork(); // your own code
percentDone += 1; // simply 1 to 100 for sample
continue = app.setProgress(percentDone/100,
'Progress: ' +
percentDone + '%';)
}
if (!continue) writeln ("User clicked Stop.");
app.stopProgress();
}