Client-Side Triggers and Operations

Client-side triggers and operations are run in the browser on the client and are implemented in JavaScript. They can be used only in dynamic server pages.

  • Client-side operations are executed by the browser when they are invoked from the server using the webactivate ProcScript command, or invoked from the browser using the JavaScript API.
  • Client-side triggers are usually activated by a user action, such as pressing a button, or an event such as an error being found during syntax checking or validation.

Client-side operations and triggers are subject to the same scope rules as server-side operations and triggers with respect to blocking and queuing. This means that if the JavaScript API is used to call a client-side operation, execution of the operation may be postponed if its input or output is blocked. ( For more information, see Input and Output Scope.)

For this reason, client-side operations and triggers are considered to be asynchronous, even when they are invoked from the client. In other words, you cannot make assumptions about when the code will be executed or when the result of executing an operation or trigger will be available. If you need synchronous behavior, you should call a normal JavaScript function rather than a client-side trigger or operation.

When the code of a client-side trigger or operation executes, JavaScript's this pointer is set to the JavaScript API Object that represents one of the following:

  • The field triggering the event (for triggers)
  • The DSP instance to which the operation belongs (for operations)
  • A FieldErrorContext object enabling the showError and clearError triggers to access field and error objects

Declaring and Implementing

Client-side triggers and operations are declared using the webtrigger and weboperation ProcScript instructions, but they are implemented as JavaScript. By declaring them in ProcScript, you can specify the scope (so that Uniface can postpone execution when required) as well as parameters.

You can choose to write the JavaScript directly in the client-side declaration in the ProcScript Editor, in which case it must be enclosed between the ProcScript keywords javascript and endjavascript. Uniface collects the JavaScript code, but does not validate it. Using the collected JavaScript, generates additional JavaScript to ensure that it conforms to the data structure required by the Uniface browser runtime. This generated code is put into a .js file with the lowercase name of the component, for example, mydsp.js.

Alternatively, you can use your preferred JavaScript editor to maintain your JavaScript implementation externally, for example in an external DSP layout or JavaScript files. This enables you to take advantage of JavaScript validation and debugging functionality that is not provided by Uniface. For more information, see Implementing External Client-Side Triggers and Operations.

Generated JavaScript Files

If you use Uniface to maintain your JavaScript implementations, the JavaScript code is put into a generated .js file with the same name as the component, for example, mydsp.js.

The output location of these .js files is determined by the JAVASCRIPT logical in the usys.ini file. If this setting is not available or not set (empty value), the output is saved in the current working directory. In a default installation, the JAVASCRIPT logical is set to the uniface\webapps\uniface\common\dspjs directory of the Uniface installation. This ensures that when you compile a DSP that has webtriggers or weboperations, the JavaScript files are generated in the correct location for the web server to find them.

During deployment, the file must be copied to the desired location, and the web server configured so that it can locate it when the associated DSP is loaded.

The runtime location of these files is determined by the $JS_BASE_URL setting in the assignment file of the Uniface Web Application Server(wasv.asn in the standard installation).The URL can specify a relative or absolute location. By default, Uniface expects to find the .js files in the ../common/dspjs directory relative to the page's base URL. For example, in the default installation, this would be http://localhost:8080/uniface/wrd/../common/dspjs.

Related Topics