1 SoftReference

1.1 History (wic_jdic_collist)

1.2 Softreference V1

1.2.1 Softreference Definition

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.

The main purposes of Filter helper are:

  • 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.
  • 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 Soft References definition.
  • Importing 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. 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.
  • 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).
  • Custom validation messages: 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.


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

With this table user can register a new record without having to access the original form that defines that field. To create a new record, the user must click on the ADD NEW option located in the drop-down menu of options in 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

Autocomplete

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

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

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.



Created by

  • Default: USER
Date created

  • Default: CURRENT
Modified by

  • Default: USER
Date updated

  • Default: CURRENT

1.2.2 Softreference Relations

Once having a proper catalog of Soft References is the time of telling each field which soft reference will use and configure the relations between the form and the soft reference. So, defining Soft Relations allows:

  • Assign a Soft References to a field
  • Map form data with the corresponding variables used in the soft reference.
  • Assign data returned by helper validation statement to be filled in form fields.


wic_jdic_softref_rel
Label Description
Table Code of the object in which the "soft reference" is included
Source column Column of the form in which the "soft reference" is included. In this column the filter criteria referenced in the table and filter method will be applied.
Form enabled condition

Evaluation condition to apply the filter. This condition is written in javascript and it is evaluated on the client at runtime.
Multiple soft references can be entered for the same pair of object and source column with different activation conditions.

For example, "${tabori}" == "gvenpedh" that this filter should be taken into account only when the content of the "tabori" field in the form is equal to gvenpedh.

Allows you to use any field entered in the output of the "wic_jrep_colout" object.

In addition, it is possible to retrieve variables from the parent form using parent(field1).

Replaces the functionality of SetExistValue.



  • Format: JS_EXPR
Filtering table

It allows to indicate the "soft reference" helper to be used to validate the source column.

A "soft reference" helper allows you to define the SQL statements for obtaining the list of available data and the condition for its validation. Its identification is defined by a table and a method code.

Therefore, the value of this field indicates the table defined in wic_jdic_softref_help.sref_tabname

Method It contains the method used in the definition of the "soft reference" helper.
SQL Vars (Form:SQL)

When in a "soft reference" the variables are used in the SQL statements, we must provide a map that relates the fields of the form with the variables used in the SQL. The syntax of this map is JSON.

For example, if in a form we have a delegation field and in the SQL the variable ${delega} is used, we must provide a map such as:

{"delegation":"delega"}



  • Format: PARSEJSON
Column mapping (Form:SQL)

Sets a map that allows you to retrieve returned columns by the validation select of the "soft reference" and applies them to form fields. All those columns that are not included in the map will not be assigned in the form even if the SQL statement selects them. The syntax of this map is JSON.

For example, if in a form we have a delegation field and the validation SQL returns a "delega" column, we must provide a map such as:

{"delegation":"delega"}



  • Format: PARSEJSON
Disable clear

Usually, when the value of a field is modified with a "soft reference", the dependent values of this field are cleared. This indicator allows this mechanism to be disabled, maintaining the value of the related fields.



  • Default: 0
  • Values:
    • 1: Yes.
    • 0: No.
Created by

  • Default: USER
Date created

  • Default: CURRENT
Modified by

  • Default: USER
Date updated

  • Default: CURRENT
Red more about Softreference V1 here

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

1.3 Softreference V2

You have a main table.

If you say nothing, the system tries to put all the joins on the tables

where you have them foreign keys and you have columns with "table.column" as name.

If you have orders and orders has FK to customer you will have the order columns ... (name without table prefix) and customer columns with table prefix.

If you define a foreign key then I no longer set the automatics because I understand that you control them.

Copy 
// ================================================================   
//SOFT (FOREIGN KEY) FIELDS (HELPERS)
// ================================================================

// Soft foreign keys can be defined by user to override existing ones or to place a soft FK on a missing hard FK. 
// When resultset is decorated it check is there are soft foreign keys defined.

// If table is decorated.

// If has soft foreign keys, only those defined are added.

// If no soft foreign key is defined, hard foreign keys are added 

// If table is not decorated hard foreign keys are added (also vertical joins).

// A code example of ORMTableDecorator function to add horizontal and vertical joins.

private final void __decorateHVJoins(JDBCConnectionWrapper conn, wic_obj_table t)
throws SQLException
{
if (t != null) {
// ================================================================
// HORIZONAL joins
// If at least one horizontal join is defined use them.
// If zero defined, try to add physical foreign keys.
// ================================================================
  LOGGER.info(String.format("Programmatically added %d logical horizonal joins", t.m_hjoins.size()));
if (t.m_hjoins.size() > 0) {
for (wic_obj_table_hjoin hjoin : t.m_hjoins) {
m_rs.addHorizontalJoin(hjoin.m_tabname, hjoin.m_sql);
}
} else {
m_rs.addImportedKeysHorizontalJoins(conn);
LOGGER.info(String.format("Automatically loaded %d pysical horizontal joins (cause no one defined in table model)", m_rs.getHorizontalJoins().size()));
}

// ================================================================
// VERTICAL Transfer vertical joins defined and that apply
// ================================================================

for (wic_obj_table_vjoin vjoin : t.m_vjoins) {
String expression = vjoin.m_disable;
// Check if this vertical relation must be shown or not
if (expression != null) {
if (m_rs.evalBoolean(expression)) {
LOGGER.info(String.format("Disabled vjoin %s by expression %s", vjoin.m_tabname, expression));
continue;
}
}
m_rs.addExportedKeysVerticalJoins(conn, vjoin.m_tabname);
}
  LOGGER.info(String.format("Programmatically added %d vertical joins", m_rs.getVerticalJoins().size()));

} else {
// ================================================================
// HORIZONTAL The keys we are using as foreign keys
// ================================================================
m_rs.addImportedKeysHorizontalJoins(conn);
LOGGER.info(String.format("Automatically loaded %d physical horizontal joins", m_rs.getHorizontalJoins().size()));

// ================================================================
// VERTICAL Our PK is being used by others (master-detail)
// ================================================================
m_rs
.addExportedKeysVerticalJoins(conn);
LOGGER.info(String.format("Automatically loaded %d physical vertical joins", m_rs.getVerticalJoins().size()));

}
}