UI Bus (Quick)

Table of Contents User Interaction Forms What the forms are built of How to compose a user interaction form User Interaction Callers Sending requests and handing responses with a caller User Interaction Handlers How user interaction handlers work

User Interaction Forms

Forms are the ontological representation of the typical user interaction components, like textual inputs, multiple selections, buttons, and so on. Forms are created by UI Callers and sent to UI Handlers to be rendered, filled by user, and sent back to UI Callers to be processed. Just like the other Ontological models, Forms can be extended, but the most usual interfacing options can be achieved with the default Forms.

What the forms are built of

There are three groups in a Form. Controls is where common UI Elements are put, including trigger buttons. Submits is for common buttons that finish a Dialog and/or do something. And Standard Buttons is for system buttons, not usually changed by applications.

A Dialog is an interaction with a Form. There are 4 different types. Main Menu is for the main screen only, and is not used by applications. Standard Dialog is the normal Dialog. Subdialog is a Dialog triggered by a previous one, which comes back after the Subdialog finishes. Message is a popup that may appear regardless of current dialog, on top of it.

How to compose a user interaction form

The first thing is instantiating a Form depending on the type of Dialog that is intended, with the right method of Form class. An instance of an Ontological Resource can be used to later fill the fields of the Form with initial values, but it is not mandatory, and not necessary in most cases.

UI Elements are added as they are created, to the group passed in their constructor. Most elements can optionally have a Label, an initial value and a Property Path. The Path is necessary for Input Elements: it is used to retrieve the value introduced by the user. It can also be used to link the Element value with the Resource used to build the Form, if any. If no Resource is used (or an empty one is) the Path can be arbitrary.

Outputs are for displaying information to the user, without requesting any information. Property Paths are not mandatory for these. Multimedia outputs will be limited by the handler rendering the information.

Inputs are Elements where a value is expected to be set by the user. There are Elements for free textual input or pre-set choices.

Submits are for issuing actions. In graphical interfaces these are buttons, so Submits are often called buttons. They have an ID used to know which Submit was issued (“pressed”) by the user.

Labels are identifiers of UI Elements and must not be mistaken for Outputs. They are only for the user to identify the different Elements.

Groups and Repeats are not Elements themselves but containers that can be used to place elements inside (Remember the Controls, Submits and Standard Buttons in the Form? Those are Groups). The Repeat is used for creating tables or lists of similar elements.

 //Application code to create a form
 // Create a normal Dialog, and don´t use Resource (it´s empty)
 Form f = Form.newDialog("Title of the Dialog", new Resource());
 // Show a simple output saying what it does
 SimpleOutput out = new SimpleOutput(f.getIOControls(), null, null, "Select a Lamp");
 // A choice selector to select one of 2 lamps
 Select1 sel = new Select1(f.getIOControls(), new Label("Lamps", null), PATH_LAMP, null, new Integer(1));
 sel.addChoiceItem(new ChoiceItem("Lamp1", null, new Integer(1)));
 sel.addChoiceItem(new ChoiceItem("Lamp2", null, new Integer(2)));
 // Buttons to turn on and off
 new Submit(f.getSubmits(), new Label("On", null), ID_SUBMIT_ON);
 new Submit(f.getSubmits(), new Label("Off", null),ID_SUBMIT_OFF);

User Interaction Callers

User Interaction Callers are the applications that want to have some kind of direct interaction with the user. They build a Form that represents exactly what they want to show to the user and what they want in return.

 //UI Caller code with the method to handle responses
 public class MyUICaller extends UICaller {
   // This is called when the response to a UI request arrives
   public void handleUIResponse(UIResponse resp) {
      // Check which submit “button” was “pressed”
      if (resp.getSubmissionID().equals(ID_SUBMIT_ON)) {
         // This is how user input is taken
         lampNumber=(Integer)resp.getUserInput(PATH_LAMP);
         // Turn on the lamp identified by lampNumber
      }
      ...
      // If no more Forms are sent here, system returns to menu
}

There can be many UI Callers in an application, but one is usually enough. It is the only thing needed for both sending and receiving on UI Bus.

Sending requests and handing responses with a caller

UI Requests ship the Forms to the UI Bus. To address the proper Handler, they are passed the target user, language, required privacy disclosure and priority level. Requests are sent with sendUIRequest method of the Caller.

 //Application code to create a caller, create a ui request with a form and send the request
 // Create the caller, which does not need extra registration info
 MyUICaller uicaller = new MyUICaller(moduleContext);
 // Create a UI request for a given user and send the Form f
 UIRequest req = new UIRequest(new User(USER_URI), f, 
   LevelRating.middle, Locale.ENGLISH, PrivacyLevel.insensible);
 // Send the UI request
 uicaller.sendUIRequest(out);

Once the request is displayed and filled by the Handler, the UI Response returns to UI Caller through handleUIResponse. The Caller can analyse which Submit triggered the response, and can extract the filled inputs from within with the right Property Path. If no more Forms are sent from there, the system will automatically go back to the Main Menu.

Requests can be sent at any time but to allow a user to manually “launch” an application dialog this must be registered in Main Menu. This is done though Service bus. A special Service Profile must be registered and there must be a Service Callee that launches the application main dialog when the Profile is requested. The profile is called by the Dialog Manager Main Menu configuration files, adding a special line for each button.

 //Provided Service code including a new profile to start app main dialog
 // Profile that starts the app UI. Service Callee must handle it and send UI request with app dialog when PROF_STARTUI is called
 ServiceProfile prof = InitialServiceDialog.createInitialDialogProfile(
      "http://my.ont.org/MyApp.owl#MyMenu ", "http://mycompany.com ", "My App Menu", PROF_STARTUI);

 //Main Menu txt file line that will display a button that will call the above profile
 /My App|http://mycompany.com|http://my.ont.org/MyApp.owl#MyMenu

User Interaction Handlers

User Interaction Handlers are special types of applications in charge of translating the Forms sent by UI Callers to a physical rendering that a user can interact with, such as a GUI, a sound output or Web page. Then interpret the user responses to fill in the information requested by UI Callers into the Form and send it back. There can be several UI Handlers in different locations, with different modalities, and the UI Callers are oblivious to them, thus achieving multi-modal and multi-location interaction.

UI Handlers are special applications that are considered Managers in the platform. Developers of everyday applications would never have to deal with UI Handler code, since the UI Bus makes these applications completely agnostic of these issues, unless a developer is interested in developing specifically a new UI Handler.

How user interaction handlers work

Despite coding UI Handlers is out of scope in this document, it may be interesting to know how they work. Every UI Request sent by UI Callers is added automatically some metadata about the addressed user. This is used by the UI Bus to find the most suitable Handler, because Handlers are registered with a set of adaptation parameters. The Handler with the most appropriate parameters is selected to render the Request, and then will have to send back the user input.

 //UI Handler code with the required methods only
 public class MyUIHandler extends UIHandler {
   // Called when a request is sent to this Handler. It must render the Form it carries and put the user input inside
   public void handleUICall(UIRequest uiRequest) { ... }
   // If some preferences of the user change, the Handler may want to adapt to them, like screen size
   public void adaptationParametersChanged(String dialogID, String changedProp, Object newVal) { ... }
   // It may happen that a dialog is interrupted for some reason
   public Resource cutDialog(String dialogID) { ... }
   ...
 }