View source | Discuss this page | Page history | Printable version   

How to add a canvas field to a Form or Grid



A canvas field allows you to add any visual component to a form or a row in a grid. This concept can be used to add a calculated field to a form and grid. Visual components which can be added are for example buttons, links and (computed) labels.

In this howto we will be adding a button and a calculated field to the form and to every row in the grid. The howto will illustrate how information from the record and form can be used to get dynamic information from the Form/Grid.

The implementation of canvas fields requires javascript development experience. See the following concept pages for background information on javascript development:

It also makes sense to study the following page: Openbravo_3_Architecture.

Note: this functionality is available in Openbravo 3.0 from MP6 and later.

Calc field example component example.png

Example Module

This howto is supported by an example module which shows examples of the code shown and discussed.

The code of the example module can be downloaded from this mercurial repository:

The example module is available through the Central Repository (See 'Client Application Examples'), for more information see the Examples Client Application project page.

Main development steps for creating a new canvas field

The development consists of 2 steps:

  1. implement the canvas itself, normally this is done in javascript.
  2. specify the canvas javascript class in the field definition of the tab/window

Implementing your canvas in javascript

The first step is to implement your canvas class in javascript. This is done in 2 steps:

The example module implements a button and a calculated field in the example-canvas-field.js file.

The first example in the file implements a button which shows the identifier of the current record:

isc.defineClass('OBEXAPP_SalesOrderActionButton', isc.OBGridFormButton);
  noTitle: true,
  title: OB.I18N.getLabel('OBUISC_Identifier'),
  click: function() {
    var info = '';
    if (this.record) {
      info = this.record._identifier;
    } else if (this.canvasItem) {
      info = this.canvasItem.form.getValue(OB.Constants.IDENTIFIER);

The second example shows a calculated field which divides 2 values from the current record and displays the result in a formatted way. It also illustrates several methods which are called when the context/environment changes (for example when a value on the form changes):

isc.defineClass('OBEXAPP_SalesOrderCalculated', isc.Label);
  height: 1,
  width: 1,
  overflow: 'visible',
  contents: '',
  initWidget: function() {
    if (this.canvasItem) {
      this.computeContents(this.canvasItem.form.getValue('grandTotalAmount'), this.canvasItem.form.getValue('summedLineAmount'));
    this.Super('initWidget', arguments);
  // is called when the form gets redrawn
  redrawingItem: function() {
    this.computeContents(this.canvasItem.form.getValue('grandTotalAmount'), this.canvasItem.form.getValue('summedLineAmount'));
  // is called when a field on the form changes its value
  onItemChanged: function() {
    this.computeContents(this.canvasItem.form.getValue('grandTotalAmount'), this.canvasItem.form.getValue('summedLineAmount'));
  // is called in grid-display mode when the canvas is created/used
  // for a record
  setRecord: function(record) {
    this.computeContents(record.grandTotalAmount, record.summedLineAmount);
  computeContents: function(val1, val2) {
    var num;
    if (!val2) {
    } else {
      num = OB.Utilities.Number.JSToOBMasked(val1/val2, 

The javascript file is registered in the example modules' ComponentProvider like this:

  public List<ComponentResource> getGlobalComponentResources() {
    final List<ComponentResource> globalResources = new ArrayList<ComponentResource>();
        "web/org.openbravo.client.application.examples/js/example-canvas-field.js", false));

Defining the canvas in the Tab-Field (ADField)

The next step is to create a new field in the tab, and set its client class field:

Calc field example field definition.png

Since 3.0MP20 it is also possible to add in-line properties in the "Clientclass" field, for example, 'OBEXAPP_SalesOrderActionButton {"title": "My Action Button"}'

The result

The result is shown in both the grid and the form:

Calc field example grid.png

Calc field example form.png

Javascript events passed to the canvas

When implementing your canvas you should take into account that the canvas is used in 3 different situations:

The last 2 cases are similar.

In grid-display mode the following applies:

In form-edit or grid-edit mode the following applies:

Adding server side actions

The button implementation can easily be extended with a server side action. Openbravo supports the action handler concept for this purpose.

Retrieved from ""

This page has been accessed 15,373 times. This page was last modified on 31 January 2013, at 22:54. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.