Web UI API

Java Web UI API Guidelines

This page provides an outline of the Java API targeted at creating Web IU. Later it may also include detailed description of specific API with application examples.

Web UI API background

Web UI API is a concept that combines several different APIs that are targeted at specific Web UI construction needs. The main idea behind Web UI API is to utilise composition and progressive interfaces (aka fluent interfaces) in order to build a Java embedded domain specific language for construction of application UI. This is in contrast to having multiple classes that need to be created in the current Swing UI or similar pure OOP approaches that explicitly rely on the MVC design pattern.

It is paramount to understand that the proposed Web UI API is strictly applicable to the TG development model based on the Fractal Objects pattern. The TG model directly influences choices for the building blocks of this API.

Web UI API composition

There four main groups within Web UI API (this may change in the future by introduction of additional groups).

• MainMenu API

  Provides a way to specify the main application menu that is accessible via FAB (Floating Action Button). Main menu items can be provided with a title, an image and a corresponding view that gets activated upon item selection. Some of the menu items are provided out-of-the-box, such as Logout.

• View API

  A set of APIs targeted at constructing views that may or may not contain a menu, and could either be associated with a main menu item, a menu item of another view with menu, or be a "floating" view in a dialog or not-dialog mode.

  An example of a "floating" view could be an entity master such as Work Activity Master that got open by tapping some work activity in Work Activity Centre.

  View API consists of several more specialised APIs:

  • Entity Centre API -- for construction of context-free entity centres.

  • Context Entity Centre API -- for construction of in-context entity centres such as "active work activities" as part of Vehicle Master; it is also envisaged that potentially one-to-many and even one-to-one associations could be represented using the same context entity centre approach.

  • Entity Master API -- for construction of entity masters, which includes support for composite masters with a menu; it is important to understand that any entity could be used as the basis for an Entity Master, be that a persistent, functional or synthesised entity.

  • Menu API -- for menu construction that could be used either as part of Entity Masters (in this case navigation between items is governed by entity master states) or for composing seemingly independent views on a single view (no restriction for navigation between menu items, useful for making hight level views that are accessed directly from the main menu and many combine various Entity Centres and Masters).

• Layout API

  An API for layouting UI widgets as part of any view such as Entity Masters or Entity Centres (e.g. selection criteria panel); it provides a way to specify different layout configurations for desktop, tablet and mobile phone devices.

• Action API

  An API for constructing actions that can be invoked either by users via a direct interaction with UI widgets such as buttons, or programmatically via an appropriate client-side API support. There should be a number of out-of-the-box actions (e.g. SaveAction, RefreshAction for Entity Masters), but also the ability to construct custom actions that are associated with functional entities that provides a flexible and consistent way of executing server-side logic.

A more detailed description for each of the above API is provided below.

View API

Entity Master API

Security

Domain security should be incorporated into the Entity Master composition logic. For example if user has no access to entity method save then editing should not be enabled. The Entity Master should include a cue to the user that this capability is not provided. For example, there could be a different title or even page background for readonly and editable entity masters.

Standard Actions and Their Events

There are five standard actions that can be performed on any entity master. Each action fires a pre- and post-event at the client side, which can be used to provide a custom UI behaviour just before the action request gets dispatched to the server and immediately after a matching action response returns from the server.

• New -- corresponds to a PUT request to EntityResource.

  An action to create a new entity instance using the server-side EntityProducer logic. Produces two client-side events:

  • NEW_PRE_ACTION
  • NEW_POST_ACTION -- should support passing of a server error.

• Refresh -- corresponds to a GET request to EntityResource.

  An action to retrieve an existing entity instance by its ID using the server-side defined fetch strategy. Non-persistent entities should never be obtained using this action or the GET method for this matter. Produces two client-side events:

  • REFRESH_PRE_ACTION
  • REFRESH_POST_ACTION -- should support passing of a server error.

• Edit -- corresponds to a HEAD request to EntityResource to check whether entity is stale (very lightweight), and a subsequent GET request in case entity is stale to the same web resource.

  An action to check an existing entity staleness and retrieve it if necessary by its ID using the server-side defined fetch strategy. Entity Masters for non-persistent entities should not support this actions.

  Produces two client-side events:

  • EDIT_PRE_ACTION -- puts UI editors into the editing mode.
  • EDIT_POST_ACTION -- should support passing of a server error.

• Save -- corresponds to a POST request to EntityResource.

  An action to save associated entity changes, which results in the invocation of the entity's companion method save.

  Produces two client-side events:

  • SAVE_PRE_ACTION
  • SAVE_POST_ACTION -- should support passing of a server error; puts UI editors into the readonly mode in case of no error.

• Cancel -- rebinds Entity Master to the original entity, which was bound before actions New or Edit that preceded cancellation; there does not seem to be a need for any requests to EntityResource.

  An action to cancel client-side changes to an associated entity.

  Produces two client-side events:

  • CANCLE_PRE_ACTION
  • CANCLE_POST_ACTION -- puts UI editors into the readonly mode.

Entity Master States

Entity Master have well defined states, which should be used to guide what actions that are associated with a master, are enabled/disabled and whether property editors can be used for entity mutation. Only actions (either standard or custom) can change the state of entity masters.

• EDIT -- a state that puts all property editors on Entity Master into an editable state; of course, some editors may not become editable due to entity semantics such as read-only properties; also, turns off/on relevant Entity Master actions.

• VIEW -- a state that puts all property editors on Entity Master into a read-only state, which prohibits direct modification of the values; also, turns off/on relevant Entity Master actions.

Actions API

Actions are probably one of the most complex Web UI building blocks as they have to explicitly combine client and server-side interaction, and always have an execution context. Therefore, an notion of an execution context and the ways to identify it is critical for this API. Also, there is a need to support at least limited, but custom client-side logic that could be specified by the application developer using Actions API in Java.

All custom actions (those constructed from scratch and not represented by some default action), are always associated with some functional entity. Such actions consist of JavaScript driven pre- and post-action and a Java action that corresponds to a method save call on the associated with action's functional entity companion object.

Action Context

An execution context for an action is critical for executing the server-side logic that is represented as method save of the functional entity (its companion object to be exact). It can be automatically determined based on the type of view the action is associated with. At this stage there are only three types of views that are relevant for a context discussion:

• Entity Master Context -- a context associated with an Entity Master.

  There are two cases here. One is related to actions effecting a master entity. Another is related to a actions effecting a dependent entity such as one-to-many and one-to-one representation (usually this means that such action can be invoked on some subview of the Entity Master that is dedicated to editing or somehow actioning a dependent to the master entity).

  For the former case the context is represented by a master entity instance itself. For the latter case, the context is represented by both the master entity and the dependent entity instances.

• Entity Centre -- a context associated with an Entity Centre that in itself is context-free (i.e. does not form part of any other view that imposes some logic onto it).

  The context for an action in this case is defined by the selection criteria (property/value pairs) and one or more entity instances that are represented in EGI.

• Context Entity Centre -- a context associated with a Context Entity Centre, that is an Entity Centre that forms part of some Entity Master.

  The context for an action in this case is defined by the master entity instance, the selection criteria (property/value pairs) and one or more entity instances that are represented in EGI. If the one-to-many association is represented using context entity centre then the same execution context is applicable.

Action's Client-Side Pre- and Post- Action

At this stage client-side pre- and post-actions should be limited to "well known" visual interactions such as:

• Starting/finishing blocking layer.
• Displaying a simple prompt with "yes/no/cancel" options, but a custom message.
• Displaying informational dialog (INFO, WARNING or ERROR) with a custom message.

And very specific, but also generic non-visual interactions:

• Assign a well known callback function to an action object that should be invoked at the specified time (e.g. action shows some entity master and the callback should be invoked at the time of that master switching into state POST_SAVE_SUCCESS).

  For example, there could be a need to enter a property value of some entity on its master, but the appropriate value does not exist yet (e.g. it is some other entity that does not yet exist). So, instead of navigating away form that master to create a missing value and then come back and select just created entity, it would be best to support an ad-hoc entity creation via its own master with an automatic assignment of the property in question immediately after that new entity has been created. At the same time, the master for that new entity could also be closed automatically.