Soft References (or 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.

Soft References parameterization 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 Soft References 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. For example, you can retrieve the bank account number after informing of the client's name.

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

To directly access the object, click on the field Manage Existing .

It allows Soft References 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, Soft References require 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, Soft References definition involves the use of Structured Query Language (SQL) , which is supposed 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 helper. 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 Soft References and where are executed (client/server).

Soft References implementation only involves two parametrization tables:

• Soft reference helper definition (wic_jdic_softref_help)
• Soft reference relations (wic_jdic_softref_rel)

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

• Table* : physical table name that is the data source.
• Method* : code that in combination with table name identifies the soft reference.
• Autocomplete statement : by default, the autocomplete functionality should return a light list of records (20 or 25 rows). Likewise, the speed of response is essential and therefore it must interrogate following indexes in the database.
  The statement is defined with two fields. Usually:
  
  1. Value code that is incorporated into the field
  2. Accessory value description for easy search
  The descriptive value can be a field value to a combination of fields. For example: "[" || code "]" || name "(" cif ")" "
  The output sort is not preset and depends on the definition in this field.
• Verify statement : SQL Statement which verifies input value and allows importing related data.
• Message : invalidate messages when an expression is fulfilled. See Invalidate Messages section.
• Options:
  • Table quick edition : with this table user can register a new record without having to access the original form that defines that field.
  • Helper object column : column name from which get the value in the data selector object.
  • Condition : filtering condition restricting displayed rows in the data selector object.

• Table* : table code to apply the soft reference.
• Source column* : source column.
• Enable expression : Javascript expression to apply this helper.
• Filtering table:
• Method :
• SQL Vars (Form:SQL) :
• Column mapping (Form:SQL) :
• Disable clear :

The implementation of Soft References 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 Soft References 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 Soft References 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 allow 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 autocomplete 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 of a simple SQL statement that 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 Soft References (Filtering Helper) 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 Soft References:

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

1. Soft reference definition (wic_jdic_softref_help)
   Menu path:

   Dictionary / Physical / Attributes / Soft references (definition)
2. Soft reference relationship (wic_jdic_softref_rel)
   Menu path:

   Dictionary / Physical / Attributes / Soft references (relationship)

The first one defines the helpers available in system, which is mainly the definition of the SQL Statements executed to enable field Soft References functionalities. Whilst the latter is the assignment of those helper definitions to the fields.

The Soft reference helper form contains all the necessary fields and components to define and maintain Soft References. 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 Soft References, 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 Soft References functionalities but not autocomplete; so it should be prevented. For that situation, is possible to use a fake SQL Statement that 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 autocomplete 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 that returns any value independently 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>

Soft References 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 use 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 functionally 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 Soft References is the time of telling each field what helper will use and configure the relations between the form and the helper. So, defining Soft Relations allows:

• Assign a Soft References 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, apart 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.

For each table and method it is possible to define, in addition to the autocomplete statement, the QBE statement. This statement will be applied exclusively on the QBE screen and follows the same implementation rules as the autocomplete statement, except that the QBE autocomplete statements don't apply Enable Expressions.

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 supposed 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 Soft References implementations:

This sample shows how to implement a defined Soft References 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 consists of:

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

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 ha el, Mitchell
• Laura, Calla ha b

This sample shows how to implement a defined Soft References 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 consists of:

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

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

The Table Colorizer feature is a grid parameterization for colorizing grid cells depending on its content, generally to emphasize the importance of a cell among a group of cells.

Table Colorizer is a tool to make grids easier to analyze at a glance.

Let's see an example of a simple grid with a table colorizer definition assigned:

As it looks, due to the colors of the grid, it becomes very easy to see which values ara bigger and which ones are not.

In addition, depending on the dataset that we want to deal with, there are different algorithms to deal with this data, and thus color the grid in the best possible way.

Table Colorizer are mainly focused on the colorization of grids, such as those containing SQL Tables or grids contained in Channels .

Its use is interesting when:

• The dataset contains numeric values to be classified
• The dataset contains discrete values (numbers or strings) from which we want to obtain the frequency of appearance

The best thing of Color Palette is that it's very easy to colorize the grid, just by indicating a palette of colors and one of the defined algorithms we have enough. At the same time, it can be added complexity to the colorizer with the use of ranges.

In first place, Table Colorizer requires the basic Axional Studio infrastructure, which includes:

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

In second place, as they can be applied to SQL Tables in Axional Studio Form Object , it is required to have any object that uses an SQL Table with at least one column for which a table colorizer is defined. And the same to Channels .

Table Colorizer implementation involves four parametrization tables:

• Table colorizer definition (wic_jdic_color_rule_def)
• Color palette (wic_jdic_color_palette)
• Table colorizer ranges (wic_jdic_color_rule_range)
• Labels (wic_jdic_lbldata)

As it is explained below, Table Colorizer functionalities only requires always the table wic_jdic_color_rule_def; It will be explained when is necessary to use the other tables below.

If the method defined in a color rule definition is 'Simple distribution', 'Quartiles distribution' or 'Repetitions', another table to obtain the color palette will be needed:

If the method defined in a color rule definition is 'By rank', another table to define the ranges will be needed:

When the table colorizer has ranges defined, it is possible to set a label to the ranges with information about the range expression, to be shown on the tooltip legend.

The implementation of Table Colorizer is achieved by adding some color rule definitions to the desired columns in a table.

The implementation of Table Colorizer is defined by one entity:

• Table colorizer definition (wic_jdic_color_rule_def)

The former defines the colorizer rule, and according to this rule involve another entities like table colorizer ranges (wic_jdic_color_rule_range) or color palettes (wic_jdic_color_palette).

The Table colorizer definition contains all the necessary information to colorize a column of a table. Each colorizer definition is identified by a unique code, that can be use by more than one column in a table.

To start defining our colorizer, the following values will be indicated:

• Description (not required)
• Consider all columns
• Show histogram
• Method
• Palette
• Gradient

The Description contains the functional description of the color rule definition. It is not required.

The Consider all columns flag indicates which columns the colorizer considers for calculating the limit values like max, min, average, etc.

It can contain two values:

• 0 (false): It considers a single column.
• 1 (true): It considers all the columns of the grid with the same color rule definition.

Example

If the flag is activated and all the columns of the table have the same color rule definition, the resulting grid will be the following:

Otherwise, if the flag is not activated, the resulting grid will be the following:

The Show histogram flag indicates if the header of the column will have a frequency histogram with a tooltip caption.

Example

If the flag is activated in all the columns of the table, the following histograms will appear below the header:

Also, if we go over the histogram, a tooltip with the caption will appear:

The implementation of Table Colorizer is achieved by adding some color rule definitions to the desired columns in a table. According to this configuration, the system handles two ways to colorize:

• By algorithm method: The user indicates a method to colorize automatically the grid.
• By ranges: The user indicates some ranges to colorize the grid according to the validation of certain expressions that can involve limit values, for example.

The Color rule definitions contain the following automatic grid colorization algorithms:

• For continuous values:
  • Simple distribution
  • Quantiles distribution
• For discrete values:
  • Repetitions

Simple distribution algorithm distributes the data of the dataset by ranges with an amplitude determined by the following formula:

This algorithm calculates the groups considering the range of the dataset, giving very good results when a large part of the data tend to be close to the arithmetic mean . Otherwise, it does not plow a good distinction when the are extreme data in out dataset.

Example

This is a dataset with the following values:

• Max: 8000
• Min: 0
• Groups: 10
• Amplitude = 800

This is the resulting grid when it is applied the simple distribution algorithm to this dataset:

The distribution of the values by groups will be the following:

• 0 - 800: 90,83 %
• 801 - 1600: 8,33 %
• 7201 - 8000: 0,83 %

In conclusion, for this dataset is it not appropaite to apply this distribution algorithm.

Quantiles distribution distributes the data of the dataset in groups of equal size. Its use is recommended when our dataset contains many extreme values (very far from the arithmetic mean).

Example

This is the resulting grid when it is applied the quantiles distribution algorithm to the same dataset as the previous example:

In this case, when creating groups with the same number of data, the interpretetion of data is better than with the simple distribution algorithm.

Repetitions algorithm distributes the data of the dataset according to the absoute frequency of each discrete value. Its use is indicated when it is important to know what values are repeated more or less.

Example

This dataset contains the most polluted cities in Europe for the last 20 years* (each row contains 6 cities, the most polluted cities every 2 months in that year).

This is the resulting grid when it is applied the repetitions algorithm to this dataset:

With this example is easy to see what cities were the most and the least polluted cities for the last 20 years.

*The data shown is not real

When one of these algorithms is being applied, there are two more values of the color rule definition that have to consider:

• Color palette
• Gradient

The Color palette defines the list of colors to be applied on the grid. This code validates to pal_code in table wic_jdic_color_palette .

The Gradient flag determines if consider the palette colors as final values, or use them to create a gradient. It will also determine the number of groups in which the dataset will be divided.

When the goal is to colorize the dataset in our own way, it is best to use the By rank method.

The Color rule ranges contains the necessary fields to indicate how to manually colorize a grid. Each colorizer range is identified by the unique code of its parent wic_jdic_color_rule_def .

To define the ranges, the following values will be indicated:

• Order (not required)
• Main color
• Secondary color
• Expression
• Label (not required)

Order indicates the order to execute the range expressions. The first ordered expression that is fulfilled will be the one that will be applied to the data. It is not required.

Main color to be applied to the cell, in case the expression returns true. It shoud contain this types of colors:

• HTML Colors (RED, BLUE, WHITE, etc.)
• Hexadecimal Colors (#FF0000, #54AB19, #000, etc.)
• RGB Colors (rgb(255,255,255), rgba(0, 120, 120, 1), etc.)

Secondary color to be applied to the cell, in case the expression returns true. Corresponds to the text color. It should contain a type of color like the main color.

The UEL Expression will determine whether apply the current color or not. It must return a boolean value:

• If true, the current color is applied.
• Otherwise, it is expected to applu the color of another item.
• In case of any item for the given palette is applicable, it is not set any color.

In order to give the maximum means for create versatil expressions, the system provides the following variables to the expression evaluator:

Label describing the color functional meaning. It will be used in tooltip caption. Its value validates with label_code in wic_jdic_lbldata . It is not required.

Example

If the Show histogram flag is activated and almost a label is applied to a range of the color rule, the label will appear on the tooltip caption.

Once having the necessary color rule definitions to colorize our tables is the time of telling each column what color rule definition will use.

To do this, indicate the color rule definition rule_code in the out_palette field of the SQL table columns.

Once having the necessary color rule definitions to colorize our tables is the time of telling each column what color rule definition will use.

To do this, indicate the color rule definition rule_code in the out_palette field of the SQL table columns.

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

This sample shows how to implement a defined Table Colorizer in a SQL Table.

The current sample is based on the following data structure:

As observed, a table with a date and information per hour about the CPU usage of a server contains our dataset.

The following SQL Table shows the content of the table:

After seeing this table, it is apparent that with colors in this table it would be much easier to see when the server is in a critical state of work. That is why it is important to apply a colorizer to the table.

The color rule definition parametrization for that case consists of:

And the color palette assigned to this color rule definition have these colors:

Once color rule definition is defined, this definition is assigned to the necessary columns of the SQL Table.

Once color rule definition is defined and assigned to the columns of the SQL Table, the grid will be automatically colorized every time it is generated, and in this case it will be shown as: