Projects:QueryList Widget/User Manual
Contents |
Introduction
On this user manual is described how to create a new widget that implements the Query/List Widget superclass.+
Developing the widget
The new widget 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.
Create the query
The HQL query is defined on the Query tab. At this moment it is not possible to validate the HQL from the application so it is recommended to design it on an external tool. Eclipse has a nice plugin for it. All columns on the select clause must have a unique alias. These aliases are used later to define the grid columns.
It is possible to use named parameters on the query. Each named parameter must have a matching Parameter defined on the Parameter tab:
- DB Column name
- it must match the name used on the named parameter.
- Fixed & Fixed Value & Evaluate Fixed Value
- when the flag is checked it is mandatory to enter the fixed value. If the Evaluate Fixed Value is checked the value has to be a javascript expression that it is validated on real time. It is recommended to add a filter by client id on all your queries using a named parameter and a fixed value with the following javascript expression: OB.getContext().getCurrentClient().id. If the parameter is not fixed it will be prompted to the user on the Edit settings window.
- Name
- is the label of the field of the parameter on the Edit Settings window.
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:
- Name
- is the label of the column.
- Display expression
- it has to match an alias of the query, it is the column of the query that will be displayed on the grid.
- Reference
- it sets the type of cell on the grid.
- Include in
- sets where is included the column.Widget view: included in all cases, Maximized view: not shown on the widget view and Exported File only included on the exported file.
- Sequence number
- sets the order of the columns.
- Width
- sets the width of the column on the grid in percentage.
- Has link & Link Expression & Tab
- it is possible to set up links on the cells to tabs of the application. The Link Expression has to be an alias of the query that returns a record id of the selected tab.
- Summarize Type
- numeric columns can be summarized on the summary row. Available options are sum, average and count.
- Can be filtered & Where Clause Left Part
- configures the ability to filter the grid by the column on the maximized view using the filter row of the grid. It is mandatory to define the left part of the where clause. This is usually the expression of the select clause identified by the alias set on the Display Expression field. It is also mandatory to define where in the HQL has to be included the where clause. There are 2 possibilities to achieve this: including the Display Expression value enclosed in "@" symbols in the where clause of the HQL or including the @optional_filters@ string.
In the example of the image. The display expression alias is salesorder. In the HQL this alias is defined like: ol.salesOrder.documentNo as salesorder. So in the Where Clause Left Part is set ol.salesOrder.documentNo. In the HQL as we want to be able to filter by all the columns and all the where clauses have to be set on the same where statement it is added AND @optional_filters@. For this column we could have added as well the following code: AND @salesorder@.
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.
And the final result:
