Fox Modes

Defines how queried data is handled once passed into FOX.

SYNTAX

<fm:run-query interface=”dbinterface” query=”query” match="XPath" mode=”string”/>

CONCEPTS

The fm:query mode attribute (overridden by fm:run-query) specifies how to process rows:

ADD-TO – (Default) Selected items are appended to the DOM regardless of what already exists
AUGMENT – Brings all information from the SELECT statement into the module. Existing records (those of matching key value) are refreshed if different to queried records (new columns can be added), and if key of selected item doesn't exist in the DOM then a new entry will be created
PURGE-ALL – All existing Target Records are removed and then replaced with the results the select statement gives
PURGE-SELECTED – Fetched records only are removed from the data DOM first, then replaced with values the query returns (based on specified key)

The PURGE-SELECTED and AUGMENT modes require Row/DOM synchronisation:

That is as row fetched, corresponding Target Record Element is sought in DOM. (E.G. One of the “F” records that exist in DOM, where F is a complex element)
For mode PURGE-SELECTED, the targeted “F” is removed, then fetched data added in its place
For mode AUGMENT, only selected items in “F” are overwritten, leaving other content unchanged. However if a selected “F” doesn't exist then another record will be added in the DOM

To synchronise Row/DOM a result record Primary Key (PK) is required:

The primary key can be a table primary key, but can also be derived as part of the query
Row/DOM synchronisation occurs where the row has the same PK values as the DOM target
Use <fm:primary><fm:key>PRIMARY KEY</fm:key></fm:primary> meta-code to define PK parts
Composite PKs are allowed, with unlimited number of key parts – useful for derived keys. To specify a composite primary key you repeat the element fm:key twice or more times within the fm:primary element.

Which mode you use is application specific and depends on what DOM data you can afford to lose:

Simple search and select screens tend to use PURGE-ALL or ADD-TO
When Querying Over data, AUGMENT is often used, so only selected columns are changed, leaving all content already in the DOM unchanged where the columns aren't selected.
When updating list data, leaving legacy entries in place, use PURGE-SELECTED

The PURGE-ALL and ADD-TO modes operate faster as no synchronisation processing occurs.

If target-path=”.” (default), only AUGMENT mode is allowed, as Fox will not allow the Subject Element to be removed.

EXAMPLES

Add-To Example

<fm:run-query name="qry-add-to" mode="ADD-TO">

<fm:query name="qry-add-to" mode="ADD-TO">
  <fm:target-path match="PRODUCT"/>
  <fm:select>
SELECT *
FROM envmgr.product
WHERE product_nr IN (1001, 1003, 1005)
  </fm:select>
  </fm:query>

Augment Example

<fm:run-query name="qry-augment" mode="AUGMENT">

<fm:query name="qry-augment">
  <fm:target-path match="PRODUCT"/>
  <fm:primary>
    <fm:key>PRODUCT_NR</fm:key>
  </fm:primary>
  <fm:select>
SELECT product_nr, (sale_price - cost_price) Profit
FROM envmgr.product
  </fm:select>
</fm:query>

Purge-All Example

<fm:query name="qry-purge-all" mode="PURGE-ALL">

<fm:query name="qry-purge-all" mode="PURGE-ALL">
  <fm:target-path match="PRODUCT"/>
  <fm:select>
SELECT product_nr, (sale_price - cost_price) Profit
FROM envmgr.product
  </fm:select>
</fm:query>

Purge-Selected Example

<fm:query name="qry-purge-selected" mode="PURGE-SELECTED">

<fm:query name="qry-purge-selected">
  <fm:target-path match="PRODUCT"/>
  <fm:primary>
    <fm:key>PRODUCT_NR</fm:key>
  </fm:primary>
  <fm:select>
SELECT product_nr, (sale_price - cost_price) Profit
FROM envmgr.product
WHERE product_nr IN (1001, 1003, 1005)
  </fm:select>
</fm:query>

EXERCISES

Please use your XX_EMPLOYEEMODULE (where XX are your initials) file for the following exercises.

Exercise 1

Create a query named “qry-userAccount3” that will select the ID, Forename, Surname and Hire_date from scott.employee_search where ID is less than 2,300. Create 4 different buttons named “action-add-to”, “action-augment”, “action-purge-all” and “action-purge-selected” which will run the query with their respective modes. Create a new namespace named “qry-modes” to set-out the actions and create a menu out to display the buttons in the order listed above.

This data should populate the structure /*/EMPLOYEE_LIST/EMPLOYEE in the Theme DOM.

Modes for Merging or Replacing DOM Data