About Website Integration with JavaScript
The Sabre Red 360 Software Development Kit provides the tools below for creating web page Red Apps with JavaScript:
-
Access to OSGi non-communications services and OSGi SRWRuntime communications services with default browser editor and view implementations
JavaScript Functions as Services
A web page Red App can use the EMU_COMMAND or EMU_RESPONSE services ** to register commands and responses with the SRWRuntime communications bus. The web page receives a service context that is serialized to JSON, which you can process any way that you want. When processing is complete, the script must return the modified context by calling the JavaScript method that is defined in redapp.xml.
Force_Focus Behavior of a JavaScript Web App in an Editor and a View
When a service that a web Red App registers is called, an app that is closed will always be opened. You configure the focus behavior on an open web app in your redapp.xml file.
The following flow describes the focus behavior of a web app with the force_focus flag.
-
A JavaScript web app is closed.
-
An end-user types a command in Sabre emulator that the web app registered.
-
Web app as an editor. A closed web app as an editor is opened in a new editor (or tab). If the force_focus attribute on ExternalHandler in redapp.xml is either omitted or set to true, the focus is moved to the new editor (new tab). If the force_focus attribute is false, focus is not moved to the new editor. Focus remains on Sabre emulator, where an end-user can continue typing, unless the app is closed and must be opened when the service is executed.
-
Web app as a view. A closed web app as a view is opened in a new view (or assistant tools panel). If the force_focus attribute on ExternalHandler in redapp.xml is either omitted or set to true, the focus is moved to the new view (new assistant tools panel). If the force_focus attribute is false, focus is not moved to the new view. Focus remains on Sabre emulator, where the end-user can continue typing, unless the app is closed and must be opened when the service is executed.
You implement active listening for commands or responses in the main plug-in. All web views or editors that are registered in redapp.xml must be in the same Red App bundle.
If multiple scripts register the same command, the Conflict Resolution dialog is displayed in Sabre Red 360. End-users must then choose the web Red App that they want to call. For information about the Conflict Resolution dialog, see the Red Apps FAQs.
Constraints for JavaScript Functions as Services
AG Command and Masking of Passwords
Red Apps are not permitted to listen for the AG command. Red Apps that listen for AG will fail certification. Red Apps can listen for all commands with an empty action_code, however, if passwords are returned, they will be masked with the xxxxxx characters.
EP Command
The SRWRuntime communications bus does not pass the EP command to the following services:
-
EMU_COMMAND
-
EMU_RESPONSE
-
Event listeners. This includes listeners in Red Apps with JavaScript.
For the procedure to implement this functionality, see Registering JavaScript Functions as Services.
Complex Event Listening
You can use JavaScript functions for event listening from web apps. When the condition for an event occurs, the web application is forced open in a browser and the event object is passed to the JavaScript listener function in JSON format.
This is useful if you need to provide important information to a web app. Whenever an event occurs, you want your web app to display the event, even if the application is closed. Suppose that a web app informs agents about important diseases or required vaccinations whenever a ticket is sold to Asia. The event is passed to the web app, passing important information to the client, even if the app is closed.
To use this functionality, your web app must use the default browser editor class DefaultWebkitEditor or the default browser view class WebkitView . (For more information about default implementations for website integration, see the topics in Website Integration Using Default Implementations.) You also register your JavaScript function as an event listener in redapp.xml with an Event ID and state, in a way that is similar to registering a Java event listener.
This functionality can be used with the following Sabre published events:
EMU_EVENT_001
EMU_EVENT_002
EMU_COMMAND
EMU_RESPONSE
Please note that EMU_EVENT_001 and EMU_EVENT_002 have been deprecated and EMU_COMMAND event should be used instead.
Force_Focus Behavior of a JavaScript Web App in an Editor and a View
When a service that a WebRed App registers is called, an app that is closed will always be opened. You configure the focus behavior on an open web app in your redapp.xml file.
The following flow describes the focus behavior of a web app with the force_focus flag.
-
A JavaScript web app is closed.
-
An end-user types a command in Sabre emulator that the web app registered.
-
Web app as an editor. A closed web app as an editor is opened in a new editor (or tab). If the force_focus attribute on ExternalHandler in redapp.xml is either omitted or set to true, the focus is moved to the new editor (new tab). If the force_focus attribute is false, focus is not moved to the new editor. Focus remains on Sabre emulator, where the end-user can continue typing, unless the app is closed and must be opened when the service is executed.
-
Web app as a view . A closed web app as a view is opened in a new view (or assistant tools panel). If the force_focus attribute on ExternalHandler in redapp.xml is either omitted or set to true, the focus is moved to the new view (new assistant tools panel). If the force_focus attribute is false, focus is not moved to the new view. Focus remains on Sabre emulator, where an end-user can continue typing, unless the app is closed and must be opened when the service is executed.
For the procedure to implement this functionality, see Registering Event Listeners in Web Apps with Javascript.
Constraints for Event Listening
AG Command and Masking of Passwords
Red Apps are not permitted to listen for the AG command. Red Apps that listen for AG will fail certification. Red Apps can listen for all commands with an empty action_code, however, if passwords are returned, they will be masked with the xxxxxx characters.
Access to OSGi Services with JavaScript
To access OSGi services without writing Java code, web apps can use a JavaScript function named SrwOsgiApi.callOSGIService to call OSGi services. The SrwOsgiApi.callOSGIService function is available to use in DefaultWebkitEditor and WebkitView implementations.
The goal of this functionality is to eliminate the need to write Java code to handle simple communication with OSGi services from a web application. In most cases, this solution will probably work for you. If these default implementations do not meet your requirements, for example, if you want to change the look or behavior, you can provide your own implementation of an editor or a view for wrapping a browser with your web application. In this case, you must implement your own communications bridge if you need to access OSGi services directly from a browser.
The Java-to-JavaScript bridge (JS bridge) exposes only a subset of OSGi services. These exposed services are referred to as whitelisted services.
For more details about calling OSGi services from a JavaScript web page and procedures for implementation, see the topics below: