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

The main purposes of Filter helper are:

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

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.

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.

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.

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).

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.

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

• Axional Studio Server, properly set up.
• Dictionary database
• A target database

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.

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).

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.

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.

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

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...

digraph Couriers { fontname = "Bitstream Vera Sans" fontsize = 8 node [ fontname = "Bitstream Vera Sans" fontsize = 8 shape = "record" ] edge [ arrowtail = "full" fontname = "Bitstream Vera Sans" fontsize = 8 ] album [ label = "{album|+ albumid : serial\l+ title : string\l+ artistid : string\l+ state : char|\l}" ] artist [ label = "{artist|+ artistid : string\l+ name : string\l+ state : char|\l}" ] album -> artist [dir=forward, label=" FK: album.artistid -> artist.artistid"] }

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

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

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

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.

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.

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.

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.

SELECT customerid, firstname
  FROM customer
 WHERE (
        UPPER(customerid) LIKE UPPER(%'[Input text...]%') OR 
        UPPER(firstname) LIKE UPPER('%[Input text...]%')
        )

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.

<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.

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.

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

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.

SELECT customerid
 FROM customer
WHERE customerid = '[Input text...]'

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.

<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.

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

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.

<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:

<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>

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.

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

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

<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        UPPER(firstname) = ${firstname?uppercase} AND
        state = 'A'
    </where>
</select>

<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        LOWER(firstname) = ${firstname?lowercase} AND
        state = 'A'
    </where>
</select>

<select>
    <columns>
        customerid
    </columns> 
    <from table='customer' />
    <where>
        customerid = ${q} AND
        (firstname = ${firstname} OR ${firstname?length} < 2) AND
        state = 'A'
    </where>
</select>

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

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

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

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

<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>

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.

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

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.

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.

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.

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:

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.

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.

... Statement 1

... Statement 2

... Statement 2

... Statement 1

... Statement 2

... Statement 2

... Statement 1

... Statement 2

... Statement 2

... Statement 1

... Statement 2

... Statement 2

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

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:

The following table shows the content of the table employee:

The helper parametrization for that case consist on:

<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>

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

The helper relation parametrization for that case consist on:

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:

• Mic hael, Mitchell
• Laura, Calla hab

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:

The following table shows the content of the table customer:

The helper parametrization for that case consist on:

<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>

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

The helper relation parametrization for that case consist on:

{"billingaddress":"address", 
"billingcity":"city", 
"billingstate":"state", 
"billingcountry":"country", 
"billingpostalcode":"postalcode"}

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.

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:

<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.

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

<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

<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.

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

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

Verification statement

<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.

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

<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:

<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.

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.

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.

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.

bts_contains(text, 'tone~')

bts_contains(text, 'tone~0.49')

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.