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

Selectors

Contents

Introduction

The Selector described in this manual combines a suggestion box with a popup window with filter and sorting capabilities. This selector has a number of important features:

This manual is targeted at consultants who want to define selectors in the Openbravo system.

Selector Example Module

The manual refers to and uses screenshots from the Selector Example module. To follow this manual it can make sense to install this module from the central repository.

After installing this module and rebuilding you can try out the selector functionality. Change Role to Openbravo Admin (or another user role having access to the example window). You can find the selector example in 'General Setup > Examples > SelectorExample'. Click on this menu option. A grid view opens, click new to open the edit form.

The form shows three selector fields: 2 business partner fields and one product field. The product field gets enabled after you have entered a value in the second business partner field.

Suggestion box 30.png


Popup window 30.png

A suggestion box is dropped-down when you start typing in the fields. You can also click on the magnifier icon to show a popup window with several filter and sorting possibilities.

Selector Concept

A selector is defined within the Application Dictionary of Openbravo. A selector is used for representing foreign key references in the Openbravo user interface. A selector is defined as part of a Reference (a domain type) definition within Openbravo.

A selector consists of three parts:

Defining a Selector

To define a new selector go to the Application Dictionary > Reference window. Defining the selector is a three-step procedure:

This manual guides you through all three steps.

Step 1: Define a Reference

The reference is used in the column definition. The definition is shown below in the screenshot.


Selector reference 30.png


A description of the fields:

Step 2: Define the Selector

After defining the reference the selector information can be entered. This is done in the reference window also. Make sure that the reference window shows the reference you have created in step 1 then click on the Defined Selector in the top right of the window. Next press the new button.


Selector header 30.png


A description of the fields:

Bulbgraph.png   Currently it is not possible to use session variables in the where clause!
Bulbgraph.png   When using properties of the entity in the whereclause always the prefix 'e.' has to be used, for example 'e.seqno'

Step 3: Defining Selector Fields

After defining the selector header the next step is to define the selector field. A selector field is used for the following things:

A selector can have zero or more selector fields. It is perfectly fine to define a selector without selector fields. The system will use the defaults which is show the identifier in the suggestion box and use the primary key of the referenced table as the value. The suggestion box is shown in the field but no popup window is shown. So this is a light-weight selector definition.

To define a selector field click on the 'Defined Selector Field' link shown in the top-right of the Defined Selector tab.


Selector field definition 30.png


The description of the fields of the Defined Selector Field:

Selector field property 30.png

Note:

Property paths, showing linked information

The selector has a very powerful feature that makes it easy to show linked information in the suggestion box and popup windows.

To give an example of linked information. For a business partner selector it is quite easy to show the identifier of the business partner category. This linked information can take multiple 'steps', so it is possible to show the name of the bank of the bankaccount of the business partner. These two examples are entered like this in the property field of the Defined Selector Field:

By using the dot (.) the path takes the next step in the model. The suggestion box in the Defined Selector Field window gives support in entering the correct path.


Propertypath example extended 30.png


This is then displayed like this in the popup window (see the bank and the business partner category columns):


Linked info 30.png


The fields which use such a property path can be used as the display field, sort by field or value field and can be used to filter and sort on in the popup grid. So they are treated as standard normal properties.

Table and Datasource

A selector can retrieve its content from a table or from a Datasource. When in the selector definition a table is defined then on the server Openbravo will create a datasource for this table. So internally for Openbravo there is no real difference between a table or datasource for the selector.

There are a number of use-cases for which using a datasource makes sense:

A datasource is implemented by a developer and then defined in the Application Dictionary. After this it can be used by consultants to define selectors.

For more information on how to implement a datasource see its Datasources page.

Translated information

The Selector and Selector Fields also allow you to specify translated versions of names and titles shown in the user interface. To use translated names and titles go to the 'Defined Selector Translation' and 'Defined Selector Field Translation' tabs. These tabs are available in the top of the window when editing a Selector or Selector Field.

Selector Examples

The Selector Example module installs a number of different selectors. These selectors can be studied to see how they are defined and what the result in the user interfac is. When you filter the reference grid on the word 'Selector' they will show up:


Selector list 30.png

Using a Selector

The next step is make use of the selector in the data model. The selector is the same as any other Reference in the Openbravo system. The Reference is used in the definition of a Column. To use the defined selector and set it in a column, go to Application Dictionary > Tables and Columns. Then select the table and the column you want to set the reference for.

Then in the reference field choose OBUISEL_Selector Reference. Then in the next combo box 'Reference Search Key' select the specific selector. In the screenshot below a Business Partner Selector is chosen.


Selector using 30.png


The column can be used to define a field in the Openbravo window in a standard way. So in the Openbravo Window/Tab/Field definition there is no special setting or handling required for the selector.

After setting the reference in the column and using it in a specific window you need to restart Openbravo to see it in action.

Changing a selector at runtime

The selector definition itself can be changed at runtime without re-compiling the system. There are no real limits to what part of the selector definition which can be changed at runtime, a non-excluding list:

Note to change a selector the module it belongs to needs to be in development. If not then it is possible that the client-side javascript (representing the selector) is not refreshed automatically.

Defining Out Fields

The usual return values from a Selector is the record id and indentifier. In some cases the developer wants to return more fields and not only this two. You can mark a Selector Field as Out Field and we'll be part of the JavaScript returned object.

Bulbgraph.png   Note: By default the id and _identifier fields are part of the returned object
Out Fields1 30.png


Using Out Fields in manual code (advanced)

You can use the New Selectors in manual code (not generated by WAD). You must include all the necessary JS imports. There is a 'empty' hook function onValueChanged that you can override in your manual window, to perform any custom action. When the user picks a row, this function gets executed. By default it doesn't do anything.

Example of function

Bulbgraph.png   To test this code, you must have a browser with console enabled, e.g. Firefox with Firebug
 
isc.OBSelectorLinkWidget.addProperties({
   onValueChanged: function(selected) {
       // selected is an object with members id and _identifier
       // plus all Out Fields
       window.console.log("%o", selected); 
     }
   }
});

In this case all instances of the OBSelectorLinkWidget will execute the same function, this example function just prints the object passed as parameter.

You can also only override the function on a particular instance.

 
// sc_C_Bpartner_One_ID is an instance of OBSelectorWidget or OBSelectorLinkWidget
sc_C_Bpartner_One_ID.onValueChanged = function(selected) {
 window.console.log("%o", selected);
};

Providing a new Selector Template (advanced)

The selector definition is converted to javascript code using a template. The template is selected in the selector (see step 2 above). It is possible for a module to add a new template which can be used for creating selectors. Creating a new template needs to be done by a developer with a good understanding of Openbravo.

Also to implement a new template it is necessary to understand the template processing and template handling functionality used by Openbravo. The Openbravo_3_Architecture page provides detailed information. It discusses both template processing, caching, i18n and also gives pointers on how to implement a custom template.

The template used for the selector can be found in the source tree of the org.openbravo.userinterface.selector module inside the org.openbravo.userinterface.selector.templates package in the selector.ftl file.

A custom template should be created inside a separate module. To make use of it define it inside the Application Dictionary > Templates.


Selector template 30.png


The main fields to set:


Selector template field 30.png


Then when defining selectors a consultant can select the custom template.

Customizing the look and feel of the selector

The styling of the selector is mostly automatically derived from the styling of other components. Only the icon on the right of the field needs to be styled, see this page for more information.

Troubleshooting

The suggestion box does not filter

Symptom: When typing in values in the selection box it does not filter, all records are shown.

Cause: This can happen when you have accidentally added boolean/yes/no fields to be 'search in suggestionbox'.

Solution: uncheck the 'search in suggestionbox' fields for the boolean/yes/no fields, searching these fields is not supported by the selector in the suggestion box.


The suggestion box is always empty

Symptom: When typing values in the selection field the suggestion box is empty or shows much less results than expected, also selecting the direct drop down results in an empty/smaller than expected list.

Cause: this happens because there are 'search in suggestionbox' fields which require a join to a table while the foreign key is not always set. Only the records which have a value in the foreign key are shown.

Solution: if the foreign key selection field is the only one on which is filtered this is fine, however if there are multiple search fields then searching on non-mandatory foreign key fields is not supported by the selector.

Advanced Topics

HQL Transformers

Bulbgraph.png   This feature is available starting from 22Q4.

Since version 22Q4, it is possible to modify an hql query entirely via java and dependency injection using transformers. To implement the new functionality follow this how to: http://wiki.openbravo.com/wiki/How_to_create_a_HQL_Based_Table#HQL_Transformers

Using foreign keys in HQL Custom queries

Since version 23Q2, it is possible to define HQL queries with foreign key columns, that is, columns that will have a combo on the column filter.

In order to do that, the HQL select clause for that property needs to point to an entity (i.e. e.organization, instead of e.organization.name). Then in the definition of the selector field we have to select a Table reference that points to the target entity.

Retrieved from "http://wiki.openbravo.com/wiki/Selectors"

This page has been accessed 30,970 times. This page was last modified on 9 May 2023, at 16:59. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.