APIs: JavaScript

The Uniface JavaScript API is a collection of object-oriented programming interfaces that can be used in dynamic server pages (DSPs) to manipulate Uniface data objects in the browser, without round-trip processing to the server.

In a typical web or mobile application, there is often enough information available on the client to process an action; a round trip to the server is only required when the data needs to be queried or stored in some way.

You can use the JavaScript APIs to:

  • Implement a web trigger or operation using JavaScript
  • Call a trigger or operation from JavaScript
  • Inspect and change a value, property, field syntax or ValRep from JavaScript
  • Add occurrences or mark them for deletion
  • Create and delete instances of DSP components
  • Implement a new widget
  • Store and retrieve data in client-side storage on the local computer or device
  • Show and clear errors for fields

Use

You can use the APIs in JavaScript that is written in triggers of DSPs. The functionality is not available in static server pages (USPs).

JavaScript is case-sensitive so you must use the correct case when calling the API functions. However, Uniface object names are case-insensitive when used in strings.

API Objects

The Uniface JavaSCript API enablesMost of the APIs map JavaScript objects (fields, occurrences, entities, and component instances), rather than DOM nodes and events, as is usual in a browser. The API maps JavaScript objects to the Uniface data objects

They represent component instances and the Uniface data they contain (component entities, occurrences, fields). The structure is hierarchical, so you must first obtain a component instance object, before you can address the entities it contains. Likewise, you must first obtain an Entity object before getting its Occurrence and Field objects.

  • uniface—the starting point for the API. Using the functions provided on this object, you can obtain a uniface.Instance object.
  • uniface.Instance—represents a component instance. It is the top-level object and can be used to obtain uniface.Entity objects representing the outer entities.
  • uniface.Entity—represents a component entity in the DSP instance. It can be used to obtain uniface.Occurrence objects.
  • uniface.Occurrence—represents an occurrence of a component entity. It can be used to obtain uniface.Field objects, as well as uniface.Entity objects that represent child entities of the occurrence.
  • uniface.Field—represents a field in an occurrence.
  • uniface.datastore—represents a browser-supported database for client-side data storage. Unlike the other objects, the datastore object represents a non-Uniface object. It is especially useful in mobile apps for storing data locally that does not need to be synchronized with a server-side database.
  • uniface.FieldErrorContext—contains information about a validation error for a field. It can only be accessed in the showError and clearError web triggers.

API Functions

Each object provides a number of functions that enable you to get information about the current object, such as its name, parent, and child objects. Some functions are common to several objects, for example getName and getParent. Other functions are available only on specific objects. For example, only the uniface.Entity object has a getOccurrence function, and the getStatus function is only available on the uniface.Occurrence object.

The JavaScript objects also provide functions for creating and deleting components (via the uniface object), adding and removing occurrences (via the Occurrence object), and manipulating data (via the Field object).

For information on the functions, see the object descriptions.

Example: JavaScript Data Addressing API

var vInstance = uniface.getInstance("MUSICLIST");
if (vInstance != null) {
  var vEntity = vInstance.getEntity("ITEMS.MUSICSHOP");
  if (vEntity != null) {
     var vOccs = vEntity.getOccurrences();
     for (var i =  0; i < vOccs.length; i++) {
	doSomethingWithOccurrence(vOccs[i]);
     }
     var vOcc = vEntity.getOccurrence(4);
     if (vOcc) {
        alert (vOcc + " has status " + vOcc.getStatus());
     }
  }
}