ERP/2.60/Projects/UI Technology/Selector Prototype
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.
The selector window/grid should support the following functions:
- 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).
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:
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.
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.
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]
- 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).
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.
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).