Projects:CanvasField

Contents 1 Status 2 Team 3 Definition 3.1 Feature overview 3.2 Users & use cases 4 Design 4.1 Functional specification 4.2 Technical specification 4.2.1 Model Changes 4.2.2 Server Side Changes 4.2.3 Client Side Changes 4.2.4 Supporting Window Personalization 4.3 User experience design 5 Planning 6 Development 6.1 Tracking 6.2 Implementation 6.3 Documentation 7 Not implemented 8 Test Plan/Topics

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.
• 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