Adding Code at the Application Level

There are several ways to add code at the application level:

• Including JavaScript files. See Including JavaScript Files.
• Executing code to set a dynamic property value. See Specifying Code in Dynamic Properties.
• Specifying the onLoad script. See Executing Code When the Application Loads.
• Specifying the onUnload script. See Executing Code When the Application Unloads.

Including JavaScript Files

The most common way of adding custom code to an application is an included JavaScript file. JavaScript files can contain function definitions, method calls, constant declarations, and so on. Functions and other constructs defined in a file can be referenced in any other location where you can specify JavaScript code, such as the Events Editor palette. The file must be loaded into memory to be accessed by the application.

JavaScript files can be created in General Interface Builder and are automatically added to your project.

A default JavaScript file, logic.js, is created and included in your project when the project is created. This file initially contains no code, and can be deleted from the project as needed. You can add JavaScript code to logic.js, or create one or more new files, partitioning code among them. For smaller applications, a single included JavaScript file is usually sufficient. For larger, more complex applications, it can be helpful to divide the code among multiple files according to feature area, class, or functional role.

To add a JavaScript file to your project, select File > New > JavaScript File. A new tab is added to the work area for editing the file contents.

When saving files in the work area, you can save changes to disk (Save), save to disk and update changes in browser memory (Save and Reload), and load or reload from disk into browser memory (Load/Reload). Files must be loaded into memory to be part of the live application.

By default, logic.js is configured to automatically load after the General Interface system files have loaded but before the application initializes. Other included JavaScript files can also be loaded automatically by right-clicking the file in the Project Files palette and selecting the Auto Load option. If a file is required only for a specific module, you can load the file when needed using the loadResource() method of the Server class.

For more information on the Auto Load options, see File Profile Dialog. For information on dynamic class loading, see Class Loading in General Interface.

Specifying Code in Dynamic Properties

Each dynamic property has an eval property that signifies if the contents of the Value field will be executed as JavaScript or simply treated as a string. This feature is useful for configuring a component when the value of a component property is determined by an external condition. For example, you could specify conditional logic in a JavaScript file included in your project, then reference the result in a dynamic property.

Dynamic properties files execute their contained JavaScript only once, when they are first loaded into the application. This means that the DateNow field in the above screenshot will reflect the date/time when the dynamic properties file first loaded.

To associate JavaScript code with a dynamic property,

1. Open an existing dynamic properties XML file or create a new one. See Creating Dynamic Properties Files.
2. Check the Eval checkbox for the property to indicate that the value should be evaluated as code.
3. Type one or more JavaScript statements separated with semicolons in the Value field.

For more information on dynamic properties, see Dynamic Properties Files.

Executing Code When the Application Loads

You can execute JavaScript code immediately after the initial component has loaded but before it's painted on-screen. The Project Settings dialog includes the onLoad Script field for this purpose.

To execute JavaScript code when an application loads, select Project > Project Settings > Deployment and type the code in the onLoad Script field. In the following figure, init() is a global function defined in a JavaScript project resource.

Executing JavaScript code before the application loads is useful for performing tasks that should complete before a user accesses your application. For example, you could add code that checks for the presence of an HTTP cookie before displaying a login dialog.

Executing Code When the Application Unloads

You can also execute JavaScript code when the browser window is unloaded. The Project Settings dialog includes the onUnload Script field for this purpose.

There are several ways to unload a browser window, including closing the window, refreshing the window, or navigating to another URL. The onUnload event allows you to save user state and do any final cleanup before exiting. This script can include one or more JavaScript statements which execute in context of the Server. The variable, this, references the jsx3.app.Server instance.

The onUnload event only fires when the browser is being unloaded. If you want to warn the user before the page is unloaded, use the onBeforeUnload event as defined for the given browser. For example,

jsx3.gui.Event.subscribe(jsx3.gui.Event.BEFOREUNLOAD, function(objEvent) { objEvent.returnValue = 'If you leave this page, your session will end.'; });