Projects:CanvasField
Contents |
Status
- Stage: Definition
- Planned Release: MP4
- Status Notes: In development
Team
- Contact: Martin Taal (martin.taal@openbravo.com)
Definition
The current ad_field definition always assumes that an ad_field is backed by a column with a reference. In MP3 a new type of field was added (widget in form), which provided a bit more flexibility. Still an even more flexible solution is needed to allow much more freedom in integrating free-form javascript components in the form. Especially computed fields which can be implemented using client side logic can benefit from this development.
Feature overview
- Allow any Smartclient canvas to be integrated in the Openbravo Smartclient form and grid
- Provide enough context information to the instantiated canvas so that it can create a form/grid/record visualization
- Re-draw/re-compute the canvas if the form is redrawn or if other information in the form changes (current record etc.).
Users & use cases
NA
Design
Functional specification
NA
Technical specification
Model Changes
Add new fields to AD_Field:
- clientImplementationClass: varchar, length 200 or more, non-mandatory. If it is set then the ad_column field can be hidden.
- ad_element_id: is visible if the clientImplementationClass is set
Server Side Changes
- the templates which generate the field representations should also output the new column (see model changes) in the field
- if ad_element_id is set in the ad_field record then the label of the field should be based on the ad_element_id in ad_field.
- the editorType OBCanvasItem should be used for this type of field
- WAD: the wad generation needs to be changed to ignore ad_field records which have ad_column_id==null
- the code in org.openbravo.client.application.window should be checked so that ad_field with a null ad_column are correctly handled.
- the template file ob-view-tab.js.ftl also generates a javascript array of property to column mapping (propertyToColumns). The code should be adapted so that the fields without column are not made part of this array.
Client Side Changes
- A new form item type should be implemented which inherits from the Smartclient CanvasItem.
- When the canvas is instantiated on the client, the framework should pass/set default information providing access to the context:
- mode: defines in what mode the canvas is created:
- grid: it is shown in a grid, the following properties are set: grid, record (see below)
- form: it is shown in a standard form
- preview: it is shown in window personalization (see handling window personalization below)
- fieldName: the name of the field which uses this canvas (can be useful if the same canvas class is used in different fields)
- grid: is set when the canvas is instantiated in the grid
- record: the record which contains this canvas (in case of grid visualization)
- form: the instance of the form, if displayed in a form.
- mode: defines in what mode the canvas is created:
- Form visualization: the main thing here is to check if the canvas item is redrawn/recomputed when the form changes or when child information changes. Most things should work fine.
- Grid visualization: as the implementation is a canvas the canvas instantiation should be implemented using the record components concept of Smartclient (see references), the changes are in ob-view-grid.js in the createRecordComponent and updateRecordComponent components. Some extra attention points:
- The record component concept instantiates only a limited set of components and re-uses them when the user scrolls. This means that one canvas instance can be pooled and later re-used for another record. Normally a canvas should know this (to update its visualization), therefore a canvas displayed in a grid should have a setRecord method.
- Grid vertical sizing: it needs to be tested how the visualization of a grid looks like if the canvas takes more vertical space than one row
- Grid horizontal sizing: it needs to be checked how/if the grids horizontal sizing works with larger canvases.
- Visualization in the statusbar: currently the statusbar only allows visualization of strings/primitive values. This needs to be reworked to show canvas items also. See ob-statusbar.js, the updateContentTitle function.
Supporting Window Personalization
Window personalization visualizes each field without a current record or form or backing grid. If the specific canvas is not able to be visualized in window personalization then on class level it should have the property: noPersonalizationVisualization, set to true. In that case window personalization should just display a box with an openbravo logo.
Note: although it can look strange, it should be possible to visualize a canvasitem in the statusbar also.
User experience design
NA
Planning
The proposal is to deliver this solution for MP4 together with a howto with some examples.
The development effort:
- Model, server side and WAD changes: 8 hours
- Implementing a new form item: 4 hours
- Handle grid visualization: 4 hours
- Status bar changes: 4 hours
- Documentation/Howto: 4 hours
- Testing: 4 hours
Development
Tracking
This feature development is tracked using the following issue(s):
https://issues.openbravo.com/view.php?id=19122
Implementation
Documentation
The new development should be explained in a HowTo which contains several examples:
- a simple client side canvas
- a display field which shows information from children/parent
- a canvas which does a call to the server to retrieve information
Howto: How_to_add_a_canvas_field_to_a_Form_or_Grid
Not implemented
The following has not been implemented:
- canvas fields can not be added to the status bar at this point
Test Plan/Topics
The test plan gives an overview of the steps to take to test this new feature.
- Happy path: to test if the feature actually works follow the howto: How_to_add_a_canvas_field_to_a_Form_or_Grid. Either by using the example module and extending it or by creating your own module.
- Test definition of a client class in the user interface. Go to the Windows, Tabs & Fields and check which fields are hidden/displayed when having an empty column value.
- Breaking tests: to try different things to break the system do the following:
- enter a new field in a window with an empty column and an empty client class definition
- enter a new field in a window with client class set to a dummy/non-existing js class value
- add a calculated field to a fieldgroup and check if it works correctly (open/close the fieldgroup)
- enter a new field with an empty column and hide/show in the grid
- enter a new field, initially set the column to empty, specify a client class, then select a column, check the result (client class should be ignored)
- do a full rebuild and try the window (with calculated fields) in classic mode (fields with empty columns should not show up)
- check help
- check audit trail
- move, hide/unhide calculated fields/columns in the grid
- try grid editing with calculated fields/columns
- window personalization: test that the calculcated fields can be moved around in the form layouter, and hidden/shown, test that the changes are persisted as part of a view
- do a short test of other windows, form editing, grid editing, filtering, sorting, check that callouts in other windows work correctly.
- check that synchronize terminology works without errors