public interface AdvancedIncludeVia

Advanced `includeVia` usage

Overview

The includeVia attribute is used in conjunction with includeFrom to resolve ambiguity when multiple foreign keys point to the same related DataSource. It allows you to explicitly specify which foreign key path should be used to retrieve data from the related DataSource.

In its simplest form, includeVia references a single foreign key field, such as:

  <field name="salesRepEmployeeNumber" type="integer" foreignKey="Employee.employeeNumber" />
  <field name="salesRepLastName" includeFrom="Employee.lastName" includeVia="salesRepEmployeeNumber" />
  <field name="accountMgrEmployeeNumber" type="integer" foreignKey="Employee.employeeNumber" />
  <field name="accountMgrLastName" includeFrom="Employee.lastName" includeVia="accountMgrEmployeeNumber" />

In more complex scenarios, where relationships span multiple DataSources or involve composite foreign keys, includeVia can define an indirect relation chain ? a multi-step path of linked DataSources leading to the target field. This allows precise control over relation resolution, especially when there are multiple possible foreign key paths between DataSources, and you want deterministic control over how relations are resolved, overriding default Smart GWT behavior.

For example, to resolve the chain Order > Customer > Employee > Office, you can use includeVia to specify which foreign keys (single-field or composite) to follow at each step.

Syntax

[dsName.]field1-field2:[dsName.]field3-field4...

"." separates a DataSource ID from its field / composite key fields
"-" separates fields that are part of a composite key
":" separates relation steps across different DataSources

Datasource names are optional if field names are unambiguous across the chain.

Behavior & Rules

Each segment must refer to a defined foreignKey (or listed in otherFKs in the corresponding DataSource.
Once includeVia is used, the chain must follow the segments as specified, without skipping intermediate DataSources.
After the last segment of includeVia, relation detection can proceed using default logic.
The same format and rules apply whether keys are single-field or composite.
Works identically for both includeVia and queryFK.

Examples

All examples are based on the DataSources shown at the end of this section.

Note that Customer > Employee relation can use foreignKey field accountMgrEmployeeNumber (Account manager) or foreignKey field salesRepEmployeeNumber (Sales representative). Also to showcase the composite foreign keys support all DataSources have composite keys consisting of ID (orderNumber,CustomerNumber etc) and domainKey field separating data into multiple domains (for example "test" and "live").

All examples below resolve the same relation chain:

  Order > Customer (via accountMgrEmployeeNumber) > Employee > Office

Example 1: Full path specified

Explicit composite keys at every step.

  includeFrom="Customer.Employee.Office.city"
  includeVia="Order.customerNumber-domainKey:Customer.accountMgrEmployeeNumber-domainKey:Employee.officeCode-domainKey"

Example 2: Partial includeVia with omitted datasource names

Unambiguous field names allow datasource names to be omitted.

  includeFrom="Customer.Employee.Office.city"
  includeVia="customerNumber-domainKey:accountMgrEmployeeNumber-domainKey"

Example 3: Minimal includeVia

Only the override for the non-default FK path is needed; the rest is resolved automatically.

  includeFrom="Customer.Employee.Office.city"
  includeVia="accountMgrEmployeeNumber-domainKey"

Example 4: Shorter includeFrom with full includeVia

The includeFrom starts mid-chain, but includeVia ensures correct relation chain from the base DataSource.

  includeFrom="Employee.Office.city"
  includeVia="Order.customerNumber-domainKey:Customer.accountMgrEmployeeNumber-domainKey:Employee.officeCode-domainKey"

Example 5: Minimal includeFrom and includeVia

System finds shortest valid path from base to target using the provided override.

  includeFrom="Office.city"
  includeVia="accountMgrEmployeeNumber-domainKey"

Datasources used in samples:

  <DataSource ID="Order" serverType="sql">
      <fields>
          <field name="orderNumber" type="integer" primaryKey="true" />
          <field name="domainKey" type="text" primaryKey="true" foreignKey="Customer.domainKey"/>
          <field name="orderDate" type="date" required="true"/>
          <field name="customerNumber" type="integer" foreignKey="Customer.customerNumber" />
      </fields>
  </DataSource>

  <DataSource ID="Customer" serverType="sql">
      <fields>
          <field name="customerNumber" type="integer" primaryKey="true" />
          <field name="domainKey" type="text" primaryKey="true" foreignKey="Employee.domainKey" />
          <field name="customerName" type="text" required="true"/>
          <field name="salesRepEmployeeNumber" type="integer" foreignKey="Employee.employeeNumber" />
          <field name="accountMgrEmployeeNumber" type="integer" foreignKey="Employee.employeeNumber" />
      </fields>
  </DataSource>

  <DataSource ID="Employee" serverType="sql">
      <fields>
          <field name="employeeNumber" type="integer" primaryKey="true" />
          <field name="domainKey" type="text" primaryKey="true" foreignKey="Office.domainKey"/>
          <field name="lastName" type="text" required="true"/>
          <field name="firstName" type="text" required="true"/>
          <field name="officeCode" type="text" foreignKey="Office.officeCode" />
      </fields>
  </DataSource>

  <DataSource ID="Office" serverType="sql">
      <fields>
          <field name="officeCode" type="text" primaryKey="true" />
          <field name="domainKey" type="text" primaryKey="true" />
          <field name="city" type="text" />
      </fields>
  </DataSource>

Interface AdvancedIncludeVia

Advanced includeVia usage