Filtering Helper is a powerful tool to ease form data entry and to enable client side data validation. It is useful when a form contains a field which value must be previously registered into a database table. So, it helps in the selection of the field's value and integrity verification.
 

1 Introduction

 

1.1 What is it?

Filtering Helper parametrizaton defined for a column enables a set of functionalities on Axional Studio Form Object input fields corresponding to that column.

 

1.2 What can I do?

The main purposes of Filter helper are:

  • Autocomplete
  • Data validation
  • Importing related data
  • Object data selector
  • Custom validation messages
 

1.2.1 Autocomplete

Field autocompletion evaluates the text typed by the user on those fields where Filtering Help is enabled. While the user is typing the form displays a list of matching values for helping the user to select the right value.

It exists a small delay between each autocomplention data request in order to soften network communication and server workload.

 

1.2.2 Data validation

After the user has filled the field the system verifies that the entered data exists in the helper destination table, according to the Filtering Helper definition.

 

1.2.3 Import related data

After the user has filled the field the system could obtain some data related to the entered value for filling some other fields or views in form.

Related data obtaining is executed together with data validation, in order to improve network communication and server workload.

 

1.2.4 Object data selector

In case of the user requires to execute complex queries, it is possible to access an Axional Studio SQL Report for filtering and getting the field value. So, that implementation takes profit of the power of Axional Studio Query By Example Form (QBE).

 

1.2.5 Custom validation messages

It allows filtering helper to display data as selectable on autocomplention or object selector list, but once selected blocks the field with an error message. It is useful, for example, for discarded or deprecated data. Hiding this data from list could be interpreted as the data doesn't exists on destination table; through this implementation data is shown but it can not be selected.

 

1.3 What do I need?

In first place, Filtering Helper requires the basic Axional Studio infrastructure, which includes:

  • Axional Studio Server, properly set up.
  • Dictionary database
  • A target database
The previous configuration is explained in detail under the Axional Studio/Setup block.

In second place, as they are applied to input fields in Axional Studio Form Object, it is required to have any object that uses the column for which a helper is defined as input field.

In third place, Filtering Helper definition involves the use of Structured Query Language (SQL), which is supossed to be known by programmer before start developing Filtering Helpers.

 

2 Architecture

 

2.1 Flow of execution

The following chart tries to explain the architecture and the system behavior of fields filtering helpers. The graph includes the whole application flow, from the user interaction to the database access. The purpose of this graph is to explain what processes intervene in the execution of filtering helpers and where are executed (client/server).

                                
Loading...
 

2.2 Dictionary tables

Filtering Helper implementation only involves two parametrization tables:

  • Helper definition (wic_jdic_softref_help)
  • Field helper relation (wic_jdic_softref_rel)

As it is explained bellow, Filtering Helper functionalities sometimes do not requires any parametrization; so the following tables are not indispensable, but very useful.

 

2.2.1 Helper definition

Menu path:
Dictionary / Physical / Attributes / Soft references (definition)
wic_jdic_softref_help
Label Description
Table Physical table name which is the data source
Method Code which in combination with table name identifies the Helper
Table quick edititon
Column Column name from which get the value in the data selector object
Condition Filtering condition restricting displayed rows in the data selector object

Autocomplete SQL Statement generating the data visible from autocomplete list

Validation SQL Statement which verify input value and allow importing related data

User created User that has created the object

  • Default: USER
Date created Creation date

  • Default: CURRENT
User updated User updated

  • Default: USER
Date updated Date updated

  • Default: CURRENT
 

2.2.2 Helper relations

Menu path:
Dictionary / Physical / Attributes / Soft references (relationship)
wic_jdic_softref_rel
Label Description
Table Table code to apply the SoftReference
Source column Source column
Enable expression Javascripr expression to apply this helper

  • Format: JS_EXPR
Filtering table Filtering table
Method Method
SQL Vars (Form:SQL) Sql vars (Form:SQL)

  • Format: PARSEJSON
Column mapping (Form:SQL) Data mapping Form - SQL

  • Format: PARSEJSON
Disable clear Disable clear

  • Default: 0
  • Values:
    • 1: Yes.
    • 0: No.
User created User that has created the object

  • Default: USER
Date created Creation date

  • Default: CURRENT
User updated User updated

  • Default: USER
Date updated Date updated

  • Default: CURRENT
 

3 Implementation

The implementation of Filtering Helper is achieved by adding some settings to the desired table and columns. According to this configuration, the system handles to types of helpers:

  • Automatic helpers (Hard Reference) are created from the database constraints configuration.
  • Explicit helpers (Soft Reference) are defined by dictionary.
 

3.1 Automatic implementation (Hard Reference)

Axional Studio Forms automatically enables Filtering Helper for those fields in form having physical database foreign keys. Filtering automatic implementation allows enabling powerful field facilities with very little configuration, which are very useful for simple tables. Automatic helpers includes the three main Filtering Helper functionalities:

  • Autocomplete
  • Data validation
  • Object data selector
 

3.1.1 Autocomplete

Autocomplete functionality is achieved by comparing the entered pattern with the destination table and column defined in the foreign key. The matching compare function accepts all rows which data pattern is contained in the destination column, not case sensitive. Matching function also considers the next alphanumeric column after the column defined by the foreign key. This column is also shown in the autocomplete list. These considerations allows the use of automatic helpers filtering by code and description just by defining the proper columns order on tables definition.

Example

Imagine you have the following data structure:

                                    
Loading...

So the SQL statement executed for the autocomplete would be like:

Copy
SELECT artistid, name
 FROM artist
WHERE (
        UPPER(artistid) LIKE UPPER(%'[Input text...]%') OR 
        UPPER(name) LIKE UPPER('%[Input text...]%')
        )

Asuming that exists the following data in the artist table:

artistid name
1 AC/DC
2 Accept
3 Aerosmith
4 Alanis Morissette
5 Alice In Chains
6 Antônio Carlos Jobim
7 Apocalyptica
8 Audioslave
9 BackBeat
10 Billy Cobham
11 Black Label Society
12 Black Sabbath
... ...

In first place, when the user types '3' in the input field, the automcomplete list will show the matching item 'Aerosmith', which have the code '3'.


In second place, when the user types 'Black', the autocomplete list will show the following matches:

  • Black Label Society
  • Black Sabbath
  • Banda Black Rio
  • The Black Crowes
  • Black Eyed Peas
 

3.1.2 Data validation

Data validation consists on a simple SQL statement which verifies that the entered data corresponds with a row from the destination table and column.

Example

Taking the previous data structure, the SQL statement executed for the data validation would be like:

Copy
SELECT artistid
 FROM artist
WHERE artistid = '[Input text...]'
 

3.1.3 Object data selector

If exists an Axional Studio SQL Report which its code corresponds to the foreign key destination table, this object is accessible from the input field for selecting data from it.

Automatic helpers are always active for those columns having physical foreign keys. If requires a custom filtering settings or even if requires to not apply any filter it will be necessary to set an explicit filtering implementation (Soft Reference).

Representation

Form fields having the Hard Reference functionality enabled are identified with a dark lightning icon.

 

3.2 Explicit implementation (Soft Reference)

An explicit implementation of Filtering Helper (Soft Reference) is necessary when business logic becomes more complex and filtering condition requires the implication of secondary tables and columns, or when are necessary the whole functionalities of Filtering Helper:

  • Autocomplete
  • Data validation
  • Importing related data (Only with Soft Reference)
  • Object data selector
  • Custom validation messages (Only with Soft Reference)

The implementation of Soft References are defined by two entities:

  • Helper definition (wic_jdic_softref_help)
  • Field helper relation (wic_jdic_softref_rel)

The former defines the helpers available in system, which is mainly the definition of the SQL Statements executed to enable field Filtering Helper functionalities. Whilst the latter is the assignment of those helper definition to the fields.

 

3.2.1 Helper definition

The Helper definition form contains all the necessary fields and components to define and maintain Filtering helpers. Each helper definition is identified by a table name and a method. The method generally corresponds to table column; it is not necessary but is useful when using automatic statements as we will see bellow.

 

Autocomplete statement

Each time the user types a character in the input field having an explicit Filtering Helper the Autocomplete statement is executed and the result of this statement is displayed to the user as an autocomplete list.

In first place, helper definition allows letting autocomplete statement in blank. In that case, the system builds an automatic statement using the helper definition table and method. As it happens with Hard Reference, the system already uses as description the next alphanumeric column in the statement.

Example

Imagine you have the following data structure:

                                    
Loading...

Automatic SQL autocomplete statement executed for helper with table customer and method customerid:

Copy
SELECT customerid, firstname
  FROM customer
 WHERE (
        UPPER(customerid) LIKE UPPER(%'[Input text...]%') OR 
        UPPER(firstname) LIKE UPPER('%[Input text...]%')
        )
If the autocomplete statement is left blank and the method doesn't correspond with a valid column for the table defined in the helper, an SQL Syntax error will occur.

If the automatic autocomplete statement doesn't covers the helpers requirements an specific statement can be defined. It is important to note that the autocomplete statement is executed frequently; for that reason, the statement must respect the triple 'E' premises:

  • Efficiency, as its executed very often it must be very light and fast.
  • Economy, the recursive execution of the statement implies lots of network communication; so, the lower data returned by the statement the better.
  • Effectiveness, the values returned by the statement should be those the user expected when introduce the pattern.
Example

The following code is a sample of an automcomplete SQL statement:

Copy
<select first='20'>
    <columns>
        customerid, firstname || ' ' || lastname
    </columns> 
    <from table='customer' />
    <where>
        (
            UPPER(customerid) LIKE UPPER('%${q}%') OR 
            UPPER(firstname) LIKE UPPER('%${q}%') OR 
            UPPER(lastname) LIKE UPPER('%${q}%')
        ) AND
        state = 'A'
    </where>
</select>

It is important to note the use of the ${q} clause in the statement; which references the input pattern typed by the user when autocomplete is requested.

The use of the select clause first='N' is a good way to improve Efficiency and Economy.

Autocomplete SQL Statement accepts both native SQL or XSQL syntax, but Axional Studio Functional Roles will only be applied with the XSQL syntax.

 
Prevent autocomplention

Sometimes are necessary some Filtering Helper functionalities but not autocomplete; so it should be prevented. For that situation, is possible to use a fake SQL Statement which returns the same value as the entered by the user.

Example

Sample of a fake automcomplete SQL statement:

Copy
<select-one>${q}, ${q}</select-one>

Leaving the autocomplete statement blank not prevent autocompletion execution. It executes the automatic statement build from table and method definition. Preventing autocomplention is achieved by using a fake SQL Statement like the one shown in the sample.

 

Validation statement

The validation statement has two purposes: verify the integrity of the input value and gather some information related to the input value for filling the form with this data. These purposes are achieved by executing the Validation SQL statement when the field value changes. Basically, execution of this statement is triggered by:

  • The user has manually modified the field and leave it.
  • The user selects a value from the automcomplete list.
  • The user selects a value from object selector list.
  • The field has been changed by the client side Javascript program.

As it happens with the autocomplete statement, leaving the Validation SQL statement blank entails the system to build an automatic statement using the helper definition table and method.

Example

Automatic SQL validation statement executed for helper with table customer and method customerid:

Copy
SELECT customerid
 FROM customer
WHERE customerid = '[Input text...]'
If the validation statement is left blank and the method doesn't correspond with a valid column for the table defined in the helper, an SQL Syntax error will occur.

If the automatic statement doesn't covers the helper's requirements an specific statement can be defined. Even this statement is much less executed than the autocomplete one it is also executed quite often; so, triple 'E' premises are also applicable to this statement.

Example

The following code is a sample of a validation SQL statement:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        state = 'A'
    </where>
</select>

Evaluation of validation SQL statement accepts the entered value as valid if the statement returns any row; otherwise, the field will be mark as invalid. So, the validation statement should return zero or one row; if return more than one row the rows after the first will be ignored. In the same way as autocomplete statement ${q} references the input pattern typed by the user.

The previous statement just verifies data integrity, but doesn't gather any extra information. This functionality is achieved by selecting more columns in the statement. All columns returned by the validation SQL statement will be ready to be filled in the form. Those columns are mapped to the form by the following rules:

  • Related columns. Columns mapping defined by helper relations to be updated in form from helper.
  • Field Label. Field Label input type defined by an EJB-DATA-TABLE box component.
  • Field Description. Field description defined by an EJB-DATA-FLOW box component.
  • JOIN Columns. All columns defined in source Form Object which its table doesn't correspond to the primary table in Form Object primary SQL Statement an which column name matches with the columns returned by the statement.
Example

The following code is a sample of a validation SQL statement having extra columns to fill a form:

Copy
<select>
    <columns>
        address,
        city,
        state,
        country,
        postalcode
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        state = 'A'
    </where>
</select>

Validation SQL Statement accepts both native SQL or XSQL syntax, but Axional Studio Functional Roles will only be applied with the XSQL syntax.

 
Prevent validation

Validation can be prevented, so the user can input a value which not exist in the destination table. However, autocomplete, object data selection and other filtering functionalities would be available. This behavior can be achieved by using a fake SQL Statement which returns any value indepedently of the input data.

Example

Sample of a fake validation SQL statement:

Copy
<select-one>'Whatever'</select-one>

It could also be interesting to retrieve related information in case of the input value exists in destination but no mark the field with error if not exist. This can be achieved by taking profit of the fact that only the first row returned by the validation statement is considered. So, if use an union clause for adding both valid SQL Statement and a fake one, if the first select returns any data, this will be considered; otherwise, the statement will return empty data:

Example

The following code is a sample of a validation SQL statement having extra columns to fill a form but prevents validation if input data doesn't exists:

Copy
<union type='all'>
    <select>
        <columns>
            address,
            city,
            state,
            country,
            postalcode
        </columns> 
        <from table='customer' />
        <where>
            customerid = ${q} AND
            state = 'A'
        </where>
    </select>
    <select-one>
        <cast type='char'>NULL</cast>,
        <cast type='char'>NULL</cast>,
        <cast type='char'>NULL</cast>,
        <cast type='char'>NULL</cast>,
        <cast type='char'>NULL</cast>
    </select-one>
</union>

Leaving the validation statement blank not prevent field validation. It executes the automatic statement build from table and method definition. Preventing validation is achieved by using a fake SQL Statement like the one shown in the sample.

 

Variables

Variables brings dynamism to helpers by using them in helper expressions. Lack of variables would entails having more helpers with small differences between them. Variables can be used in:

  • Autocomplete statement
  • Validation statement
  • Object condition

Variables are defined simply by using them, no previous definition in helper is required. Variables value will be defined later by the relations definition. If a variable has no value defined by the helper relation an error will occur. Variable names are arbitrary, they have no relation with the helper tables nor methods.

Example

Sample of a validation SQL using variable ${country}:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        country = ${country} AND
        state = 'A'
    </where>
</select>
 
Built in functions

It exits the possibility to apply some build functions to the variable that enables extra functionalities:

Function Description Sample
?uppercase Convert the string to uppercase letters

The values 'Mark' or 'mark' for the variable firstname will return the same response:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        UPPER(firstname) = ${firstname?uppercase} AND
        state = 'A'
    </where>
</select>
?lowercase Convert the string to lowercase letters

The values 'Mark' or 'mark' for the variable firstname will return the same response:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        LOWER(firstname) = ${firstname?lowercase} AND
        state = 'A'
    </where>
</select>
?length Returns the length of a string

Do not consider the comparison of firstname if its value has a lengt lower than 2:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        (firstname = ${firstname} OR ${firstname?length} < 2) AND
        state = 'A'
    </where>
</select>
?literal Literally replaces the value into the statement

Literally replace the value of the variable condition:

Copy
<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        ${condition?literal}
    </where>
</select>

If the value of condition is state = 'A', the execute SQL Statement will be:

Copy
SELECT customerid
  FROM customer
 WHERE customerid = ? AND
       state = 'A'
 

Constants

It exists a set of constants that can be also used in helper expressions. As it occurs with variables, constants can be used in:

  • Autocomplete statement
  • Validation statement
  • Object condition
Constant Description
$CODE Returns the code of the Axional Studio Form Object in which the helper is executing.
$DBMS Returns the application database in which the helper is executing.
$LANG Returns the user language codes, defined by ISO 639, an international standard that assigns two- and three-letter codes to most languages of the world.
$USER Returns the user code

Constants are used with the sintax $CONSTNAME, directly in the helper statement.

Example

Sample of a autocomplete SQL using constants:

Copy
<select first='20'>
    <columns>
        customerid, firstname || ' ' || lastname
    </columns> 
    <from table='customer' />
    <where>
        (
            UPPER(customerid) LIKE UPPER('%${q}%') OR 
            UPPER(firstname) LIKE UPPER('%${q}%') OR 
            UPPER(lastname) LIKE UPPER('%${q}%')
        ) AND
        state = 'A' AND
        customerid != $USER
    </where>
</select>
 

Object data selector

Filtering Helpers enables the functionality to use Axional Studio Reports for selecting data for an input field. Object data selector is much less intuitive than autocomplete and is also less efficient. Besides, it causes adding extra buttons to the form which make it heavier for the eyesight. In counterpart, enables the use of QBE queries to perform complex search. Taking this into account, the us of object data selector must be rationed to those cases strictly necessary.

Object data selector is enabled by specifying a column in the Help object box. If so, the object used as data selector corresponds with the table name identifying the helper. The defined column references the column of the destination object to take the value from an place it in the source field.

Optionally, it could be defined a condition that will be added to the where clause of the destination object. The same way as helper statements, the object data selector condition can reference:

  • Input text: ${q}
  • Variables: ${varname}
  • Constants: $CONSTNAME

The main difference is that those expressions are literally replaced in the condition to be send as an object condition clause. For that reason, when defining the condition it must be considered the type of the variables, possible nulls, etc. The main consideration is that alphanumeric variables should be placed between quotes.

Example

Sample of a object data selector condition using variables:

Copy
customer.country = '${country}' AND customer.state = 'A'
 

Invalidate messages

Invalidate messages allows selecting values for the input field but blocking the field with a custom invalidate message. That is, both autocomplete list and object data selector display some values as selectable that won't be able to be chosen at the end. This functionaly is useful when having invalid or deprecated values that must be shown to inform the user the row exists, but them must not be selected.

Invalidate messages is implemented by the Message box in the Helper definition form. The box provides a transactional table with two columns:

  • Expression: UEL Expression evaluated with the data returned by the validation statement each time it is executed.
  • Label: Localizable label to be shown as field error if the expression is evaluated to true.

That is, each time the validation statement is executed and some row is returned the system evaluates the messages tables; if founds any invalidate message that accomplish the expression shows the corresponding message as an error for the field.

 

3.2.2 Define relation

Once having a proper catalog of helpers is the time of telling each field what helper will use and configure the relations between the form and the helper. So, defining helper relations allows:

  • Assign a Filtering Helper to a field
  • Map form data with the corresponding variables used in helper.
  • Assign data returned by helper validation statement to be filled in form fields.
 

Apply Expression

One form field could have assigned more than one helper. However, at the moment of validation only one helper would be applied to a field. So, the applied helper will be the one among the set of helpers defined by the field which the defined apply expression is evaluated to true depending on the state of the form.

Let the apply expression blank in a helper assignment implies that this helper will be applied in case that any other helpers apply expression is accomplished. Taking this into account, the following statements must be considered:

  • In case of a field with only one helper the apply expression must be blank.
  • In case of a field where none apply expression is accomplished during the form data entry, none helper will be applied.
  • In case of more than one apply expression are accomplished, only one of them would be arbitrarily applied. So, apply expression should be exclusive.
 

Map form data to helper

As it is said before, helpers use variables in its statements to constraint the set of available rows for the field. Those variables are collected from the source form, so it is required to define the relations between the form data and these variables. These relations are defined in the form to SQL mapping using a key/value JSON syntax where the keys reference the data source and the values are the name of the variables referenced by the helper.
The data source has different types: form fields, parent fields and constants. Each type is referenced using a different syntax:

Syntax Type Description Sample
{ 'colname' : 'varname' } Form field Obtains the value from a field in form { 'artistid' : 'artist' }
{ 'adapter.colname' : 'varname' } Main statement field Obtains the value from the object main statement, in case it is not the main data, for example, in SQLTables { 'adapter.albumid' : 'album' }
{ 'parent.colname' : 'varname' } Parent field Obtains the value from a field in the parent form { 'parent.albumid' : 'album' }
{ 'constant.value' : 'varname' } Constant Sets a constant value to the variable { 'constant.A' : 'state' }
 

Update form fields from helper

Finally, helper validation statement appart from validate the input value gathers some others values that can be filled in the source form. This functionality requires two steps:

  1. Define a helper validation statement which select some columns.
  2. Define the relation between the columns defined in the validation statement and the source form fields.

The first step has been explained before in the Helper definition section. The second step is achieved by defining the SQL to form mapping field. Similar to the form to SQL mapping it uses a key/value JSON syntax, where the key references a field from the source form and the value references a column returned by the helper validation statement. Unlike form to SQL mapping, the SQL to form mapping can only reference form fields, so the syntax is simpler.

 

3.3 Dictionary overriding

Axional Studio Soft References allow dictionaries overriding. That is, modifying the functionality of Soft References defined in lower modules or dictionaries. Soft Reference overriding can be achieved by overriding both helper definition (wic_jdic_softref_help) or helper relation (wic_jdic_softref_rel). Even though, it is strongly recommended to use helper relation overriding. On one hand, because it has a more simple structure; on the other hand, because helper definition overriding might cause some issues as it is shown on the sample cases bellow.

For the following examples, it is supossed that exists two dictionaries: wic_sample1, wic_sample2. Where wic_sample2 has higher priority than wic_sample1, so the definitions of wic_sample2 prevails over those of wic_sample1.

Example

Good use

This case shows an example of good practice of overriding a helper relation.

Helper relation (wic_jdic_softref_rel):

Dictionary Object Source Column Destiny table Method
wic_sample1 customer supportrepid employee employee_fullname
wic_sample2 customer supportrepid employee employee_fullname_cust

Helper definition (wic_jdic_softref_help):

Dictionary Table Method Autocomplete statement Messages
wic_sample1 employee employee_fullname
Copy
... Statement 1
wic_sample2 employee employee_fullname_cust
Copy
... Statement 2
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON

Result:

Property Value
Table employee
Method employee_fullname_cust
Autocomplete statement
Copy
... Statement 2
Messages
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON

Notice that, as the high priority dictionary (wic_sample2) has overridden the helper relation by pointing to the employee.employee_fullname_cust it inherit all its properties.

Example

Not recommended

This case shows a correct parameterization, but not recommended, of overridding a helper definition.

Helper relation (wic_jdic_softref_rel):

Dictionary Object Source Column Destiny table Method
wic_sample1 customer supportrepid employee employee_fullname

Helper definition (wic_jdic_softref_help):

Dictionary Table Method Autocomplete statement Messages
wic_sample1 employee employee_fullname
Copy
... Statement 1
wic_sample2 employee employee_fullname
Copy
... Statement 2
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON

Result:

Property Value
Table employee
Method employee_fullname
Autocomplete statement
Copy
... Statement 2
Messages
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON

Notice that, as the high priority dictionary (wic_sample2) has overridden the helper definition employee.employee_fullname it inherit its properties from the wic_sample2 dictionary.

Example

Bad use

This case shows an incorrect parameterization of overridding a helper definition.

Helper relation (wic_jdic_softref_rel):

Dictionary Object Source Column Destiny table Method
wic_sample1 customer supportrepid employee employee_fullname

Helper definition (wic_jdic_softref_help):

Dictionary Table Method Autocomplete statement Messages
wic_sample1 employee employee_fullname
Copy
... Statement 1
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON
wic_sample2 employee employee_fullname
Copy
... Statement 2

Result:

Property Value
Table employee
Method employee_fullname
Autocomplete statement
Copy
... Statement 2
Messages
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON

Notice that, as the high priority dictionary (wic_sample2) has overridden the helper definition employee.employee_fullname it inherit its properties from the wic_sample2 dictionary; but it takes the messages from the wic_sample1 dictionary. It happens because of the architecture of the application; as it not exists any data for the given table and method in wic_sample2 dictionary, the system searches in the other dictionaries. The way to solve this issue is by using a helper relation override instead of overriding the helper definition.

Good use resolving the issue:

Helper relation (wic_jdic_softref_rel):

Dictionary Object Source Column Destiny table Method
wic_sample1 customer supportrepid employee employee_fullname
wic_sample2 customer supportrepid employee employee_fullname_cust

Helper definition (wic_jdic_softref_help):

Dictionary Table Method Autocomplete statement Messages
wic_sample1 employee employee_fullname
Copy
... Statement 1
Expression Label
city == 'Barcelona' LBL_AT_BARCELONA
city == 'London' LBL_AT_LONDON
wic_sample2 employee employee_fullname_cust
Copy
... Statement 2

Result:

Property Value
Table employee
Method employee_fullname_cust
Autocomplete statement
Copy
... Statement 2
Messages
 

4 Samples

The following section presents a set of samples with the most interesting cases of uses of Axional Studio Filtering Helper implementations:

 

4.1 Filtering by first name and last name

 

4.1.1 Introduction

This sample shows how to implement a defined Filtering Helper in a Customer form for a field identifying the employee which give it support, so the user could search the employee by its first or last name.

The current sample is based on the following data structure:

                                
Loading...

The following table shows the content of the table employee:

employeeid lastname firstname
1 Adams Andrew
2 Edwards Nancy
3 Peacock Jane
4 Park Margaret
5 Johnson Steve
6 Mitchell Michael
7 King Robert
8 Callahan Laura
 

4.1.2 Helper definition

The helper parametrization for that case consist on:

Column Description Value
Table Source of data table employee
Method Identifying code of the current helper employee_fullname
Autocomplete statement SQL Statement filtering by both first name and last name
Copy
<select first='20'>
    <columns>
        employee.employeeid, 
        employee.lastname || ', ' || employee.firstname
    </columns> 
    <from table='employee' />
    <where>
        (UPPER(employee.lastname) LIKE UPPER('%${q}%') 
        OR UPPER(employee.firstname) LIKE UPPER('%${q}%'))
    </where>
</select>
Validation statement SQL Statement verifying that the entered code corresponds with a valid employee.
Copy
<select>
    <columns>
        employee.employeeid
    </columns> 
    <from table='employee' />
    <where>
        employee.employeeid = ${q}
    </where>
</select>
 

4.1.3 Define relation

The helper relation parametrization for that case consist on:

Column Description Value
Object Code of form object containing the field to assign the helper customer
Source Column Name of the field to apply the helper supportrepid
Destiny table Table identifying the applicable helper. Corresponds with the previously defined table. employee
Method Method identifying the applicable helper. Corresponds with the previously defined method. employee_fullname
 

4.1.4 Execution

Once both helper and relation are defined, column 'Id. support' in SQL Object 'customer' allows the user to search the employee code by its first and last name. For example, of the user types 'ha', the autocomplete list will show:

  • Michael, Mitchell
  • Laura, Callahab
 

4.2 Fill form with related data

 

4.2.1 Introduction

This sample shows how to implement a defined Filtering Helper in an Invoice form, where the invoice customer could be selected by first and last name; furthermore, after selecting the customer all the customer data will be automatically filled in the invoice form (Address, City, etc.).

The current sample is based on the following data structure:

                                
Loading...

The following table shows the content of the table customer:

customerid address city state country postalcode
1 Av. Brigadeiro Faria Lima, 2170 São José dos Campos SP Brazil 12227-000
2 Theodor-Heuss-Straße 34 Stuttgart null Germany 70174
3 1498 rue Bélanger Montréal QC Canada H2G 1A7
4 Ullevålsveien 14 Oslo null Norway 0171
5 Klanova 9/506 Prague null Czech Republic 14700
6 Rilská 3174/6 Prague null Czech Republic 14300
7 Rotenturmstraße 4, 1010 Innere Stadt Vienne null Austria 1010
8 Grétrystraat 63 Brussels null Austria 1010
9 Sønder Boulevard 51 Copenhagen null Denmark 1720
...
 

4.2.2 Helper definition

The helper parametrization for that case consist on:

Column Description Value
Table Source of data table customer
Method Identifying code of the current helper customerid
Autocomplete statement SQL Statement filtering by both first name and last name
Copy
<select first='20'>
    <columns>
        customer.customerid, 
        customer.firstname || ' ' || customer.lastname
    </columns> 
    <from table='customer' />
    <where>
        (UPPER(customer.firstname) LIKE UPPER('%${q}%') 
        OR UPPER(customer.lastname) LIKE UPPER('%${q}%'))
    </where>
</select>
Validation statement SQL Statement verifying that the entered code corresponds with a valid customer. Notice that the statement gather all the columns that will be filled in form.
Copy
<select>
    <columns>
        customer.customerid,
        customer.address,
        customer.city,
        customer.state,
        customer.country,
        customer.postalcode
    </columns> 
    <from table='customer' />
    <where>
        customer.customerid = ${q}
    </where>
</select>
 

4.2.3 Define relation

The helper relation parametrization for that case consist on:

Column Description Value
Object Code of form object containing the field to assign the helper invoice
Source Column Name of the field to apply the helper customerid
Destiny table Table identifying the applicable helper. Corresponds with the previously defined table. customer
Method Method identifying the applicable helper. Corresponds with the previously defined method. customerid
Column Mapping
(from SQL to Form)
Mapping those columns returned by the validation SQL Statement that will be filled in form.
Copy
{"billingaddress":"address", 
"billingcity":"city", 
"billingstate":"state", 
"billingcountry":"country", 
"billingpostalcode":"postalcode"}
 

4.2.4 Execution

Once both helper and relation are defined, column 'Id. customer' in SQL Object Invoice allows the user to search the customer code by its first and last name. For example, of the user types 'Mark', the autocomplete list will show:

  • Mark Philips
  • Mark Taylor

Furthermore, when choose one the two proposals the fields of the Invoicing will be filled the information of the selected customer.

 

4.3 Example III

From the previous example, show the steps to follow for can program a message, which, inform if the customer is given off sick in case to want select it in the form of invoice.

To start with it is necessary to go to the method 'customer id' in the soft reference helper of the table customer, to add the column of state in the code SQL of the sentence of verification. Now the code will remain of the following shape:

Copy
<select>
    <columns>
        customer.customerid,
        customer.address,
        customer.city,
        customer.state,
        customer.country,
        customer.postalcode,
        customer.status
    </columns> 
    <from table='customer' />
    <where>
        customer.customerid = ${q}
    </where>
</select>

To continuation in the field Expression of the section Message declares the sentence SQL that will do it appear. For this defines that, whenever it put the identifier of a customer that is given off sick, show the message. Also it defines the field Labels, in which will indicate the code of the label of form the description of which, will be the text that will show the message.

  • Expression: '${status}'== 'B'

  • Label: LBL_CUSTOMER_DROP


To realize the testing has to situate in the form invoice, and tries aggregate one with the identifier of a customer that have off sick. In our case is the '9' and appears the message in addition to preventing aggregate the bill.

 

5 Frequently asked questions

 

5.1 How implementing the autocomplete in a field without verifying the integrity?

To define this type of soft reference shows an example in which to him object Customer, can happen a Id.Support without that it verify the integrity.

How the table of filter is Employed it is necessary to head to the Soft reference Helper and define it of the following shape:

Autocomplete statement

Copy
<select>
    <columns>
        employee.employeeid, employee.firstname || ', ' || employee.lastname
    </columns>
    <from table='employee' />
    <where>
        (UPPER(employee.firstname) LIKE UPPER('%${q}%') OR 
         UPPER(employee.lastname) LIKE UPPER('%${q}%') OR
         (employee.employeeid || <whitespace/>) LIKE ('%${q}%'))
    </where>
</select>

Verification statement

Copy
<select-one>'' dummy</select-one>

In the reference relation indicates the relation of the table origin with the destiny method.

Finally if it goes to him object Customers to realize the checking, will be able to observe how in Id.Support follows appearing the autocomplete and in putting a nonexistent identifier, there is not integrity verification.

 

5.2 How defining the sentence integrity verification without the autocomplete?

To define this type of soft reference shows an example in which to him object Employee, can happen an addressee of the report without that it appear the autocomplete but, without that it do the integrity in case to put an identifier of employee that do not exist.

Head to the soft reference helper and define the sentences SQL of the following shape:

Autocomplete statement

Copy
<select>
    <columns>
        wic_dual.dummy
    </columns>
    <from table='wic_dual' />
    <where>
        1==0
    </where>
</select>

Verification statement

Copy
<select>
    <columns>
        employee.employeeid
    </columns>
    <from table='employee' />
    <where>
        employee.employeeid || <whitespace/> = ${q}
    </where>
</select>

In the reference relation indicates the relation of the table origin with the destiny method.

Finally if it goes to the object to realize the checking, can see how in Report recipient no longer appears the autocomplete, but in putting an identifier that does not exist the integrity verification if it works.

 

6 Text search queries

The system allow to realize Basic text search queries from Helpers. For this it is necessary to use the following tag:

Copy
<text-search table='product' column='product_name' fuzzy='y'>${q}</text-search>

The tag has the following attributes:

<text-search
    table='table'
    column='column'
    fuzzy='yes|no'
/>

In order to use this feature it is necessary the database server must support Text Search Queries and that the column on which realizes the query has the suitable index.

For example:

Copy
<union>
    <select>
        <columns>*</columns>
        <from table='product' />
        <where>
            <text-search table='product' column='product_name' fuzzy='y'>${q}</text-search>
            AND (${product_class_id} IS NULL OR product_class_id = ${product_class_id})
        </where>
    </select>
    <select>
        <columns>*</columns>
        <from table='product' />
        <where>
            <text-search table='product' column='brand_name'>${q}</text-search>
            AND (${product_class_id} IS NULL OR product_class_id = ${product_class_id})
        </where>
    </select>
</union>

See this documentation to how prepare the database to allow BTS queries over fields in Informix agent.

 

6.1 Fuzzy queries on Informix

A fuzzy search searches for text that matches a term closely instead of exactly. Fuzzy searches help you find relevant results even when the search terms are misspelled.

To perform a fuzzy search, append a tilde (~) at the end of the search term.

Example

For example in Informix to search term bank~ will return rows that contain tank, benk or banks.

Copy
bts_contains(column, 'bank~')

You can use an optional parameter after the tilde in a fuzzy search to specify the degree of similarity. The value can be between 0 and 1, with a value closer to 1 requiring the highest degree of similarity. The default degree of similarity is 0.5, which means that words with a degree of similarity greater than 0.5 are included in the search.

Example

The degree of similarity between a search term and a word in the index is determined by using the following formula:

Copy
similarity = 1 - (edit_distance / min ( len(term), len(word) ) )

The edit distance between the search term and the indexed word is calculated by using the Levenshtein Distance, or Edit Distance algorithm. The min() function returns the minimum of the two values of the len() functions, which return the length of the search term and the indexed word. The following table shows the values used to calculate similarity and the resulting similarity between the search term tone and various indexed words.

Term Length of term Word Length of word Edit distance Similarity
tone 4 tone 4 0 1.00
tone 4 ton 3 1 0.67
tone 4 tune 4 1 0.75
tone 4 tones 4 1 0.75
tone 4 once 4 2 0.50
tone 4 tan 3 2 0.33
tone 4 two 3 3 0.00
tone 4 terrible 8 6 -0.50
tone 4 fundamental 11 9 -1.25
Example

The following query searches for words with the default degree of similarity of greater than 0.50 to the search term tone:

Copy
bts_contains(text, 'tone~')

This query returns rows that contain these words: tone, ton, tune, and tones. Rows that contain the word onceare not included because the degree of similarity for once is exactly 0.50, not greater than 0.50. The following query would include the rows that contain the word once:

Copy
bts_contains(text, 'tone~0.49')

If the number of indexed tokens that match your fuzzy query exceed 1024, you receive the following error: (BTSB0) - bts clucene error: Too Many Clauses

To solve this problem, you can make the query more restrictive or you can recreate the bts index with the max_clause_count index parameter set to a number greater than 1024.