public class BBjJavaScriptExecutor
The BBjJavaScriptExecutor is a BBj Custom Class that manages JavaScript code execution in a BBjHtmlView control, providing the ability to queue and debounce JavaScript execution.
- Debouncing: instead of immediately firing off several events in quick succession, if you choose to debounce the scripts then they will be batched together to improve performance.
The batch size depends on how many scripts are enqueued, the amount of time that passes between their enqueing, and the defined Rate. Do NOT debounce scripts from which you are expecting
a return value, as the return value will be associated with the entire batch, not an individual line of JavaScript. If you do need a valid return value, use the executeImmediately() methods.
- Rate: the number of milliseconds that must expire without enqueing any more scripts before the executor flushes the enqueued scripts on the client. The default Rate is 200ms, although you can override this by using the constructor that specifies a Rate time.
- Execute Key: The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first and the first script will not be executed. You do not have to specify a key value with several of the execute() methods. The main point of the key is that if you think that you may be executing the exact same script several times, then reusing the same key is a way to have only the last instance of the script be executed. For example, if you execute a redraw() JavaScript function whenever the user resizes a window, then using the script as the key ensures that it won't get called dozens of times sequentially as the user is resizing the window.
- Execute Priority: The script's priority in the queue, starting from 0 and incrementing by ones. If you specify a priority, it will be used as the script's index in the queue (a ListOrderedMap). This MUST start at 0 and increment, or you will get an indexing error on the queue. If you use an execute() method that does not specify a priority, then the scripts will be added sequentually to the queue and executed in the order in which they were added.
Although this class offers several execute() methods for the most flexibility, the most common usage will be the execute(BBjString script!, BBjNumber debounced!) signature, as
it reuses the provided script for the key, you can control debouncing, and sequential execution is desired (without having to keep track of priority levels).
If scripts are queued for execution, they will eventually be executed in the BBjHtmlView control either when the widget code explicitly calls the executor's flush() method, or after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed.
Note that every time you queue a new script it will reset the Rate timer. That means that if you are queueing up scripts for execution in quick succession, then they will all be executed in a batch after the last script is queued. If you are queueing up scripts occasionally, meaning longer than the Rate timer, then each script will end up being executed before the next one has been queued.
Note: The executor handles JSNI automatically so you don't have to check for BUI and adjust the window and document JavaScript objects.
Example use cases:
Since this class is meant to be used with a BBjWidget, then it will automatically queue up scripts if the BBjWidget's getIsReady() returns false.rem Create a new executor object specifying the rate time of 200ms where #this! is an rem instance of the custom class (assuming the application is object-oriented) executor! = new BBjJavaScriptExecutor(#this!, 200) rem Have the executor enqueue then execute the JavaScript stored in the script! variable. rem The "1" indicates that it should be debounced, or batched. executor!.execute(script!, 1) rem Have the executor immediately execute the provided JavaScript and return the result rem in a BBjString or Object viewType! = executor!.executeImmediately("window.calendar.view.type;")
| Modifier and Type | Field and Description |
|---|---|
BBjNumber | Debug!A boolean that determines whether the plug-in should run in debug mode - when true it will use unminified Javascript and display the debugger in GUI and log messages to the console. |
BBjHtmlView | HTMLView!The BBjHtmlView control that will execute the JavaScript. |
BBjNumber | Rate!The number of milliseconds before the executor tries to flush the enqueued scripts on the client. |
BBjNumber | SuppressBuiDebouncing!A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in BUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" may help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in BUI. |
BBjNumber | SuppressGuiDebouncing!A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in GUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" will help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in GUI. |
| Constructor and Description |
|---|
BBjJavaScriptExecutor(BBjWidget widget!)A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and taking the default flush rate of 200ms. |
BBjJavaScriptExecutor(BBjWidget widget!, BBjNumber rate!)A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and the flush rate in milliseconds. |
| Modifier and Type | Method and Description |
|---|---|
Object | execute(BBjString key!, BBjString script!, BBjNumber debounced!, BBjNumber priority!)Executes the provided JavaScript code on the client, specifying all available parameters. |
Object | execute(BBjString script!, BBjNumber debounced!, BBjNumber priority!)Executes the provided JavaScript code on the client and uses the script itself as a key with the specified priority. |
Object | execute(BBjString key!, BBjString script!, BBjNumber debounced!)Executes the provided JavaScript code on the client without a priority, which is a more typical use case. |
Object | execute(BBjString script!, BBjNumber debounced!)Executes the provided JavaScript code on the client using the script itself as a key and without priority, which is the typical use case. |
Object | execute(BBjString key!, BBjString script!)Executes and debounces the provided JavaScript code on the client without a priority. |
Object | execute(BBjString script!)Executes and debounces the provided JavaScript code on the client using the script itself as a key and without a priority. |
Object | executeImmediately(BBjString script!)Executes the provided JavaScript directly in the BBjHtmlView control without debouncing so that it can return a valid return object as a generic |
BBjJavaScriptExecutor | flush()Flushes the executor's queue by iterating over the enqueued scripts, combining them into a single batch, executing them on the BBjHtmlView control. The widget should call this method once when it is ready to begin the execution process. This is normally this done after the 'ON_PAGE_LOADED' event has fired. If this method isn't explicitly called by the widget, then it will be called automatically after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed. |
void | onFlush(BBjTimerEvent event!)An internal method serving as a BBjTimerEvent callback which will be invoked when the executor timer's count down reaches 0 to flush the enqueued scripts. |
public BBjNumber Debug!A boolean that determines whether the plug-in should run in debug mode - when true it will use unminified Javascript and display the debugger in GUI and log messages to the console.
public BBjHtmlView HTMLView!The BBjHtmlView control that will execute the JavaScript.
public BBjNumber Rate!The number of milliseconds before the executor tries to flush the enqueued scripts on the client.
public BBjNumber SuppressBuiDebouncing!A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in BUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" may help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in BUI.
public BBjNumber SuppressGuiDebouncing!A BBjNumber acting as a boolean that determines whether the executor should override script debouncing in GUI. Defaults to "0", meaning scripts will be batched instead of executed immediately. Setting this to "0" will help to increase the communication performance between BBj and the JavaScript library/object inside the BBjHtmlView control in GUI.
public BBjJavaScriptExecutor(BBjWidget widget!)A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and taking the default flush rate of 200ms.
BBjWidget widget! The BBjWidget instance.public BBjJavaScriptExecutor(BBjWidget widget!, BBjNumber rate!)A constructor that creates a new BBjJavaScriptExecutor object to be used with a BBj plug-in that extends the BBjWidget plug-in class, specifying the BBjWidget and the flush rate in milliseconds.
BBjWidget widget! The BBjWidget instance.BBjNumber rate! The number of milliseconds that should elapse before the executor flushes the JavaScript code on the client.public Object execute(BBjString key!, BBjString script!, BBjNumber debounced!, BBjNumber priority!)Executes the provided JavaScript code on the client, specifying all available parameters.
BBjString key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.BBjString script! The JavaScript code to execute.BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).BBjNumber priority! The script's priority value that serves as its index in the queue. This MUST start at 0 and increment, or you'll get an indexing error on the queue.public Object execute(BBjString script!, BBjNumber debounced!, BBjNumber priority!)Executes the provided JavaScript code on the client and uses the script itself as a key with the specified priority.
BBjString script! The JavaScript code to execute.BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).BBjNumber priority! The script's priority value that serves as its index in the queue. This MUST start at 0 and increment, or you'll get an indexing error on the queue.public Object execute(BBjString key!, BBjString script!, BBjNumber debounced!)Executes the provided JavaScript code on the client without a priority, which is a more typical use case.
BBjString key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.BBjString script! The JavaScript code to execute.BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).public Object execute(BBjString script!, BBjNumber debounced!)Executes the provided JavaScript code on the client using the script itself as a key and without priority, which is the typical use case.
BBjString script! The JavaScript code to execute.BBjNumber debounced! A BBjNumber acting as a boolean that determines whether the executor will debounce the script (1) or execute it immediately (0).public Object execute(BBjString key!, BBjString script!)Executes and debounces the provided JavaScript code on the client without a priority.
BBjString key! The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first, and the first script will not be executed.BBjString script! The JavaScript code to execute.public Object execute(BBjString script!)Executes and debounces the provided JavaScript code on the client using the script itself as a key and without a priority.
BBjString script! The JavaScript code to execute.public Object executeImmediately(BBjString script!)Executes the provided JavaScript directly in the BBjHtmlView control without debouncing so that it can return a valid return object as a generic Object.
BBjString script$ The JavaScript code to execute.public BBjJavaScriptExecutor flush()Flushes the executor's queue by iterating over the enqueued scripts, combining them into a single batch, executing them on the BBjHtmlView control.
The widget should call this method once when it is ready to begin the execution process. This is normally this done after the 'ON_PAGE_LOADED' event has fired. If this method isn't explicitly called by the widget, then it will be called automatically after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed.
public void onFlush(BBjTimerEvent event!)An internal method serving as a BBjTimerEvent callback which will be invoked when the executor timer's count down reaches 0 to flush the enqueued scripts.
BBjTimerEvent event!