ERP/2.60/Projects/UI Technology/Selector Prototype

Contents 1 Introduction 2 Designed User Interface 3 Main development activities/parts 4 Selector Window/Grid 5 Selector Field 6 Client-side datastore and JSON Data Server 7 Selector Definition in the Application Dictionary 8 (Re-)Generation of the popup selector window 9 QA and the UI Prototype 10 Behavior 11 Keyboard handling 12 Openbravo Core changes 13 Other aspects 14 Selector DataModel 14.1 Selector 14.2 Selector Suggestion Box Fields 14.3 Selector Grid Fields 15 Smartclient Research Topics 15.1 Formatting/Validating of dates/numbers 15.2 Mapping OB References to Smartclient Simpletypes 15.3 Saving multiple edit actions in one transaction

Introduction

As a prototype of a new UI technology the proposal is to develop a new selector.

The selector is used when entering data in a many-to-one (foreign key) field in the Openbravo UI. The selector consists of a field and a popup window which allows a user to search for values (a business partner, a product, etc.). Currently in Openbravo selectors are completely hand-coded.

This page describes the development steps which need to be executed the implement the selector as a prototype for a new UI technology.

A change with the current selector is that the new selector will be defined in the Application Dictionary just like any other window/tab/field. The selector is then generated from the model. The prototype should support dynamic regeneration at runtime.

Designed User Interface

The proposed user interface has been designed using Smartclient components. See here for the result.

Main development activities/parts

The selector prototype development consists of the following main parts:

• the popup selector grid: this is the popup window (or an overlay in the browser) which shows a grid with records which can be selected by the user.
• the selector field itself: the field in the form from which the user can start the popup. Next to the popup the field should also support suggestion box behavior.
• Client-side datastore and JSON Data Server: the selector grid reads its data from the Openbravo backend using a client-datastore and to-be-implementation JSON data service. The JSON data service should support querying, filtering, sorting, paging. The suggestion field will make use of the same JSON data service.
• Reference and Application Dictionary Definition: the selector is defined in the application dictionary. This means new tables (in the AD) to define the selector and its columns and a new reference definition to make it possible to use the new selector in AD_Column and in AD_Field.
• Generation of the selector grid from the Application Dictionary: runtime (re-)generation of the selector popup window should be supported.
• Changes in Openbravo core to support a new selector Openbravo core needs to be adapted, to support a new reference as part of a module and to support the generation of the new selector field in standard Openbravo forms.

Selector Window/Grid

The selector window/grid should support the following functions:

• scrollable
• sort by column (possibly multi-column sorting)
• filter/search by column:
• column resizing and column order
• column hiding
• initially only single selection

The grid should use labels and elements defined in the Application Dictionary. Also attention should be paid to internationalization and formatting of numbers/dates.

The development will go through the following steps:

• first develop an example grid (business partners) which reads data from a static data source, so a static html example
• add new functionality such as: sorting and filtering
• add resizing of column, column hiding and column re-ordering
• support selecting a value

The example grid will be used as a basis to develop templates which are used for the dynamic re-generation of the popup window (see later section).

Selector Field

The selector field is used in a standard Openbravo form. The selector field consists of the following parts:

• an edit field to enter a value manually
• a button to open a popup window to select a value
• receive the selected value back from the popup/window
• a suggestion/autocomplete feature which reads values from the JSON datastore backend

For the development of the selector field the following two aspects are important to test/check:

• can Smartclient and dojo be used in one form, are there any javascript clash/issues
• how is the performance (loading javascript, client side rendering), as Smartclient is used only for one field the performance hit should be minimal.

Client-side datastore and JSON Data Server

The popup window and suggestion box will read data from the backend. On the client side the data store concept will be used. The Smartclient data store can work with a JSON data service on the server. The JSON data service should support a specific api which includes querying (filtering) and sorting.

Therefore a new Openbravo JSON service will be developed and delivered as a separate module. The new module can be used independently from this prototype making it possible to implement other UI's on top of Openbravo.

The JSON data service will also support a specific api focused on suggestion box features. The api used by the suggestion box is similar to the one used by a grid but there can be specific attention for performance as (when typing) the server can get hit by multiple requests in a short period of time.

For the initialy prototype the JSON data service does not need to support update/insert behavior.

Selector Definition in the Application Dictionary

The selector definition in the Application Dictionary has different aspects:

• a new reference type should be added to allow selecting this reference in the column definition
• the grid/popup definition should be defined in the application dictionary

The development of this part should start with a small design phase (defining the AD model).

A question is how specific parameters can be specified for different types of references. For example a selector/suggestion box for a business partner can have different parameters (like the name to show in the suggestion box) than a suggestion box for products.

(Re-)Generation of the popup selector window

The selector popup window is generated from the AD definition. The development of the generation logic has several parts:

• develop templates on the basis of the first example grid, templates for the overal grid and for individual columns (by column type and using field definitions)
• develop re-generation of the UI when the window definition changes (automatically at save)
• implement a mechanism to automatically reload the re-generated UI, see this link

QA and the UI Prototype

The UI prototype should also be used as a basis for testing and checking QA processes in a new UI framework. There are 2 main components: the new field and the popup window. The idea is to develop two selenium tests to test these new components. The selenium tests can not be developed in the beginning of the prototype development as there should first be a UI to test. Possibly the static example can be used for the selenium testing.

Behavior

The behavior is described in a scenario.

The scenario starts on the form. Once the focus is in the field and the user starts typing, suggestions appear in a list box. This is standard behavior of SmartClient´s list box. For the prototype it will be good to examine whether we can use two different columns for the DataSource, for example Name and Key. The suggestions will then be combined in the list box.

The moment a value is selected from the list box, the list box will close and the chosen value will be used in the field.

Once the user clicks the UI selector button, a modal layer pops up. The current value is used as a column filter. This step is perhaps redundant and counter intuitive. The current behavior for filters is that the UI selector popup always starts with the current selection as a filter but the reason for opening the UI selector is that you want to search for another value than the current one. Leave it open for now.

Column filters show an X button to the right of the keyword filter in case a keyword is present. Clicking the X removes the filter and updates the grid.

After having clicked the X the focus needs to be in the column filter and the user can start typing. Here the adaptive filter of SmartClient is used. Clicking OK in the modal layer will port the selected value (row) in the grid back to the field in the form. Clicking Cancel will take the user back to the form where the field value remains unchanged.

Note: the images in the scenario show SmartClient´s demo grid columns that Openbravo ERP does not use, such as SKU or Item. In the prototype we should replace them by other attributes, such as Name and Key.

Keyboard handling

Specific attention needs to be paid to keyboard short cuts which should be implemented in the field and the grid. For example make it possible to select a record using just the keyboard and to 'jump' quickly through the suggestion box list.

The short cuts should preferably be the same and use the same keyboard short cuts as currently in Openbravo.

Openbravo Core changes

The UI prototype should be developed as a module. This requires several changes in Openbravo core:

• a module should be able to add a new reference type
• the XML engine should be able to generate the new field using the new reference definition.
• [Other changes to be added]

Other aspects

• Initially the selector grid will only support single-select.
• The JSON data service will initially only support read/query access and no update access (not required for the prototype).

Selector DataModel

This part of this wiki document describes the data model of the Selector. Initially it will focus on how to model the suggestion box as well as the popup grid behavior.

The selector consists of two main parts, the suggestion box and the popup grid.

Selector

Defines the selector 'header' information:

• Name: unique name
• Description: free format description
• Title: the page/grid title
• Help/Comment: the help text or comment displayed in the popup grid
• Tracing fields: updated, createdBy etc.
• Type: defines if only a suggestion box should be displayed, only a popup or both, values: suggestion box, popup, both
• AD_Table: the table shown in the selector grid/suggestion box, note: can be empty in which case it is a computed selector.
• Handler: a class which handles the json data requests for both the suggestion grid and box, if not set then the default json data handler is used.

A selector has one or more suggestion box fields and one or more suggestion popup fields.

Selector Suggestion Box Fields

Selector Grid Fields

A selector can have one or more selector grid fields. The grid fields have the following columns:

• name: a unique name, if AD_Column is set then the AD_Column.name is used.

title: a translatable name used as the column header

• AD_Column: a link to the column represented by the field, should be a column of the table defined above. Is not mandatory.
• AD_Reference: if the AD_Column is not set, can be used to create computed column fields.
• sortable: if true then the grid/suggestion box can be sorted on this column
• filterable: if true then a filtereditor is shown for this grid.

Smartclient Research Topics

Formatting/Validating of dates/numbers

Smartclient offers several ways of setting the date format logic. This can be set at different levels (type, class level, form, field level). Within Smartclient formatting patterns are specified in a way which is not completely the same as in Java. It needs to be studied how we can match the Openbravo formatting definition with the Smartclient approach. Can be considered together with the topic related to matching OB Reference with Smartclient simple types.

Mapping OB References to Smartclient Simpletypes

Smartclient has a simple type system which is extendable with custom types. It is possible to define validators and formatters in custom types. The research topic is to study and implement how the OB reference system can be used to generate OB simple types which can be used in Smartclient.

The OB simple types should also be used to define OB datasources.

Saving multiple edit actions in one transaction

There are use cases where it is required to save multiple edit actions in one server-side db transaction. Smartclient supports this in its Pro version. For the LGPL version this needs to be implemented. Smartclient offers a concept called queueing which can be used on the client to send multiple edit-requests in one http-requests. However after studying the forum/docs it seems that we need to implement our own format for sending multiple DSRequests in one http request. This needs to be studied further (search for queue or 'mass update' in the forums and docs).