How to create a Datasource Widget

Introduction

This How To article describes how to create a new widget that fetches its data from an user-defined datasource. The generic documentation about widgets can be found here.

A related How to article explaining how to embed a widget into a generated Window/Tab can be found in this link.

Developing the datasource

The new datasource like all developments must belong to a module. Create a new one if you still don't have it.

Implementing the Java datasource

By default Datasources cannot be executed by Portal users. To make them accessible for portal users they must implement org.openbravo.portal.PortalAccessible interface.

This test datasource is going to return the following Data:

Row 1 - 1

Row 2 - 2

The first column is a String, and the second column is a Number.

<source lang="Java"> package org.openbravo.datasourceWidget;

import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; import java.util.Map;

import org.openbravo.service.datasource.ReadOnlyDataSourceService;

public class TestDatasourceForWidget extends ReadOnlyDataSourceService {

 /**
  * Returns the count of objects based on the passed parameters.
  * 
  * @param parameters
  *          the parameters passed in from the request
  * @return the total number of objects
  */
 @Override
 protected int getCount(Map<String, String> parameters) {
   return 2;
 }

 @Override
 protected List<Map<String, Object>> getData(Map<String, String> parameters, int startRow,
     int endRow) {
   List<Map<String, Object>> result = new ArrayList<Map<String, Object>>();

   Map<String, Object> firstRow = new LinkedHashMap<String, Object>();
   firstRow.put("column1", "Row 1");
   firstRow.put("column2", 1);
   result.add(firstRow);

   Map<String, Object> secondRow = new LinkedHashMap<String, Object>();
   secondRow.put("column1", "Row 2");
   secondRow.put("column2", 2);
   result.add(secondRow);

   return result;
 }

} </source>

Defining the datasource in the application dictionary

Select the module where your developments belong, give a name to the datasource, and specify its java class name.

File:Datasource.png

Datasource definition in the application dictionary.

Developing the widget

The new widget like all developments must belong to a module. Create a new one if you still don't have it.

Create the widget

All the widget definition is done in the Widget window.

Create a new widget class:

Widget title

is the title that appear on the widget header. Put here a short sentence that describes the widget.

Superclass & Widget superclass

leave the flag unchecked and select the Query/List superclass widget from the drop/down menu.

Height

set up any value, the Query/List override this value setting up the height based on the number of rows.

Enable for all users

Check it if the widget has to be available to all roles. Otherwise leave unchecked and give access to the desired roles on the Widget Access tab.

As the widget is implementing a superclass widget some parameters might have been created to the new widget. On the Query/List case the Number of Rows parameter is created automatically. This sets the number of rows visible on the grid.

File:DatasourceWidgetDefinition.png

Widget definition

Select the datasource

The datasource is selected on the Query tab. Select the Datasource option in the Type field, and then select the previously defined selector in the Datasource combo.

File:SettingTheWidgetDatasource.png

Setting the datasource of the widget.

Create the columns

Once the query is defined and the necessary parameters created is time to define the columns that will be available on the grid on the Column tab.

In this example two column have the be defined. The first one is a string named column1 and the second one is a number named column2 (see Java datasource definition).

Datasource widget example.

Adding the widget to your workspace

Once the widget is done if you have access to it you are able to add it to your workspace. It is not needed to compile anything.

On the Add widget menu select your new widget. If all the parameters have a default value or are fixed you will see the widget added on the workspace. Otherwise you will be prompted to fill the parameters.

This is the final result:

Datasource widget example.