Zen Tables

<tablePane>

<tablePane> is the XML projection of the versatile %ZEN.Component.tablePaneOpens in a new tab class. To place a table on a Zen page, place a <tablePane> component inside the page class XData Contents block.

This chapter describes the various component and auxiliary classes that Zen supplies to support tables. The following list summarizes the XML elements used to represent these classes in XData Contents. The most important of these is <tablePane>:

• “<tablePane>” — Draws an HTML table based on an SQL query. Each row in the resultset is displayed as a row in the table. A <tablePane> may contain the following elements, as needed:

  • “<parameter>” — Each <parameter> element provides one of the parameters required to construct the <tablePane> query.

  • “<column>” — Each <column> element specifies layout, style, and behavior details for a particular column in the resulting table. <column> elements are optional when the table displays all columns in the resultset. <column> elements are required when a <tablePane> needs to select which columns in the resultset to display.

  • “<condition>” — Each <condition> element defines one data-specific detail that applies to rows and cells within the table. For example, cells that contain a certain value might display a certain background color, such as red to indicate an error condition. The specific cells that contain this value might be different each time the table refreshes. Zen keeps track of these details for you and colors all cells appropriately.

• “<tableNavigator>” — Automatically provides a standard set of buttons for moving through the pages of a multipage table.

• “<tableNavigatorBar>” — An alternative to <tableNavigator>, this element provides extra buttons to help users navigate large, multipage tables.

<tablePane> has the following general-purpose attributes.

<tablePane> offers many additional attributes that you can use to configure layout, style, and behavior. The following topics describe them.

Data Sources

A <tablePane> element must indicate a data source for the table in one of the following ways:

• “Specifying an SQL Query”

• “Generating an SQL Query” by providing a simple description that Zen uses to generate an SQL statement

• “Referencing a Class Query” to obtain a result set

• “Using a Callback Method” to obtain a result set

• “Changing the Data Source Programmatically” for a table at runtime

The next several topics describe each option in detail.

Regardless of which option you use, all techniques support the maxRows attribute. It controls the size of the data returned. The following table provides maxRows details.

Specifying an SQL Query

A <tablePane> can provide a complete SQL statement as the value of its sql attribute. For example:

<tablePane id="table"
           sql="SELECT ID,Name FROM MyApp.Employees
                WHERE Name %STARTSWITH ? ORDER BY Name"
           >
     <parameter value="Z"/>
</tablePane>

The following table provides sql details.

Attribute

Description

sql

The value of this attribute is a complete SQL statement, which Zen executes at runtime to provide the contents of the table. The <radioSet>, <select>, <dataListBox>, <dataCombo>, and <repeatingGroup> components also support the sql attribute. You may provide any input parameter values for the SQL query by placing <parameter> elements inside the <tablePane> container. For details, see the section “Query Parameters.”

The sql attribute is the XML projection of the %ZEN.Component.tablePaneOpens in a new tab property sql. Therefore, the sql attribute value must escape any XML special characters. For example, in place of the less-than symbol < you must substitute the XML entity &lt; as follows:

sql="select * from infonet_daten.abopos where lieferadresse=? and status<9"

The following table lists XML special characters that cause problems when they appear in sql strings, and the XML entities to substitute for them.

XML Entities for Use in sql Attribute Values

Character	XML Entity	Description
>	>	Right angle bracket or “greater than” symbol.
<	&lt;	Left angle bracket or “less than” symbol.
&	&amp;	Ampersand.
'	&apos;	Single quotation mark or apostrophe. A string enclosed in single quotes needs the &apos; entity to represent the ' character.
"	&quot;	Double quotation mark. A string enclosed in double quotes needs the &quot; entity to represent the " character.

Unlike most other %ZEN.Component.tablePaneOpens in a new tab properties, you cannot set the sql property from the client at runtime. You can set it only from XData Contents. This is because sql is an encrypted attribute. The sql attribute value is encrypted (using the current session key) when it is sent to the client. If this value is returned to the server, it is automatically decrypted.

This prevents users from seeing the definition of an SQL statement if they view page source within their browser and prevents client logic from constructing arbitrary queries. For security reasons, query activities should always be restricted to the server.

Generating an SQL Query

The <tablePane> component supports attributes that allow you to automatically generate the query based on a simple description. This approach is similar to using a callback method, as described in a later topic, except that Zen generates the callback method for you, based on your description of the query. <dataListBox> and <dataCombo> also supports these attributes.

Attribute	Description
groupByClause	An SQL GROUP BY clause such as "Year,State". The groupByClause value can be a literal string, or it can contain a Zen #()# runtime expression.
orderByClause	An SQL ORDER BY clause such as "Name,State". If not provided, then whenever the user clicks on a column header, the next query contains the appropriate ORDER BY clause based on the user’s choice. The orderByClause value can be a literal string, or it can contain a Zen #()# runtime expression.
tableName	The name of the SQL table that provides the data for the table. This value is used in the FROM clause for the generated query. The tableName value can be a literal string, or it can contain a Zen #()# runtime expression.
whereClause	An SQL WHERE clause such as "Name='Elvis'". When a whereClause is provided in the <tablePane> definition in XData Contents, this sets an initial value for the whereClause property of the tablePane object. If client-side or server-side code later changes the value of this whereClause property, the new value overrides the original value. This means you can initially set up a table to show only certain values, but another line of code can change the whereClause value, causing your users to see a different set of values when it refreshes. For example, if any column filters are defined in this table, Zen dynamically creates a WHERE clause for the <tablePane> based on the current filter values selected by the user. The whereClause value can be a literal string, or it can contain a Zen #()# runtime expression.

To have the <tablePane> generate an SQL query, you must do the following:

1. Provide a value for the tableName attribute.

2. Do not provide values for the sql, queryClass, queryName, or OnCreateResultSet. All of these attributes take precedence over the behavior described in this topic.

   After you satisfy the first two conditions, Zen assumes a "columns" value for dataSource.

3. Define the names of one or more columns by providing <column> elements inside the <tablePane>. You must define at least one column or Zen generates a “Missing SELECT list” error.

4. You can add query parameters by providing <parameter> elements inside the <tablePane>.

5. You can add clauses for the generated query by providing the <tablePane> attributes groupByClause, orderByClause, or whereClause, or by allowing defaults to prevail as described in the table above.

The following is a simple example:

<tablePane id="table"
    tableName="MyApp.Employee">
    <column colName="ID" hidden="true"/>
    <column colName="Name"/>
</tablePane>

This <tablePane> example generates an SQL statement similar to the following:

SELECT ID,Name FROM MyApp.Employee

Zen executes this query to provide the contents of the table. In the example, the ID column is marked as hidden. This means that its value is fetched (it can be used for conditions or actions) but not displayed. For details about hidden and other <column> attributes, see the section “Table Columns.”

Note:

A generated SQL query can be useful for tables with column filters.

Referencing a Class Query

A <tablePane> can reference a pre-existing class query to obtain a %ResultSetOpens in a new tab object. The following components also support this approach: <radioSet>, <select>, <dataListBox>, <dataCombo>, and <repeatingGroup>.

Attribute	Description
queryClass	The name of the class containing the query. You must also provide a value for queryName.
queryName	The name of the class query that provides the %ResultSetOpens in a new tab for this <tablePane>. You must also provide a value for queryClass.

You may provide any input parameter values for the query by placing <parameter> elements inside the <tablePane>. For example:

<tablePane id="table"
           queryClass="MyApp.Employee"
           queryName="ListEmployees">
    <parameter value="Sales"/>
    <parameter value="NEW YORK"/>
</tablePane>

The value of the parameter in the <tablePane> is the value used to create the %ResultSetOpens in a new tab object. It overrides any default value set in the class query in all cases.

Using a Callback Method

A <tablePane> can use a callback method to obtain a %ResultSetOpens in a new tab object. The following <tablePane> attributes support this approach. <dataListBox>, <dataCombo>, and <altJSONSQLProvider> also support these attributes.

Attribute	Description
OnCreateResultSet	Name of a server-side callback method in the Zen page class. For more information, see OnCreateResultSet.
OnExecuteResultSet	Name of a server-side callback method in the Zen page class. For more information, see OnExecuteResultSet.
showQuery	showQuery works only if an OnCreateResultSet callback is used to generate the table, and only if this callback sets the queryText property of the QueryInfo object to contain the text of the query. Of the various components that use callback methods to generate SQL queries, only <tablePane> and <dataCombo> support the showQuery attribute. If showQuery is true, the Zen page displays the SQL query used to provide the contents of the <tablePane> or <dataCombo> component. This is useful for troubleshooting purposes, during application development. The default showQuery value is false. showQuery has the underlying data type %ZEN.Datatype.booleanOpens in a new tab. See “Zen Attribute Data Types.” The showQuery value can be a literal string, or it can contain a Zen #()# runtime expression.

OnCreateResultSet

Name of a server-side callback method in the Zen page class. This method instantiates the %ResultSetOpens in a new tab object and set any %ZEN.Auxiliary.QueryInfoOpens in a new tab “QueryInfo Properties” appropriately. Zen invokes this method whenever it draws the table, automatically passing it the following parameters:

• %StatusOpens in a new tab — an output parameter for method status

• %ZEN.Auxiliary.QueryInfoOpens in a new tab — the QueryInfo object for the <tablePane>

The callback must return a %ResultSetOpens in a new tab object. The following is a valid method signature. Also see the detailed example following this table:

Method CreateRS(Output tSC As %Status,
     pInfo As %ZEN.Auxiliary.QueryInfo)
     As %ResultSet
{ }

To use the above method as the callback, the developer would set OnCreateResultSet="CreateRS" for the <tablePane>.

If defined, OnCreateResultSet takes precedence over any other techniques for providing data for a <tablePane>.

OnExecuteResultSet

Name of a server-side callback method in the Zen page class. This method executes the %ResultSetOpens in a new tab object returned by the OnCreateResultSet callback. Zen automatically invokes the OnExecuteResultSet callback after the OnCreateResultSet callback, passing it the following parameters:

• %ResultSetOpens in a new tab — the result set from OnCreateResultSet

• %StatusOpens in a new tab — an output parameter for method status

• %ZEN.Auxiliary.QueryInfoOpens in a new tab — the QueryInfo object for the <tablePane>

Optionally, you can suppress invocation of the OnExecuteResultSet callback by setting the QueryInfo queryExecuted property to true at the end of the OnCreateResultSet callback.

The OnExecuteResultSet callback must return a%ZEN.Datatype.booleanOpens in a new tab indicating whether or not the result set was executed. The following is a valid signature for this callback:

Method ExecuteRS(myRS As %ResultSet,
     Output pSC As %Status,
     pInfo As %ZEN.Auxiliary.QueryInfo)
     As %Boolean
{ }

To use the above method as the callback, the developer would set OnExecuteResultSet="ExecuteRS" for the <tablePane>.

Callback Example

The following is a detailed example of using a callback method to create a %ResultSetOpens in a new tab for a tablePane. The callback method constructs a dynamic SQL statement in response to current values of tablePane properties sortOrder and sortColumn. The tablePane automatically passes these values to the callback method as the corresponding properties of the input %ZEN.Auxiliary.QueryInfoOpens in a new tab object.

Also note how the method places the SQL statement text in the queryText property of QueryInfo before exiting. If the <tablePane> showQuery value is true, this table displays itself, plus the query that generated it.

Method CreateRS(Output tSC As %Status,
                pInfo As %ZEN.Auxiliary.QueryInfo) As %ResultSet
{
    Set tRS = ""
    Set tSC = $$$OK

    Set tSELECT = "ID,Name,Title"
    Set tFROM = "MyApp.Employee"
    Set tORDERBY = pInfo.sortColumn
    Set tSORTORDER = pInfo.sortOrder
    Set tWHERE = ""

    // Build WHERE clause based on filters
    If ($GET(pInfo.filters("Name"))'="") {
        Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
                "Name %STARTSWITH '" _ pInfo.filters("Name") _ "'"
    }
    If ($GET(pInfo.filters("Title"))'="") {
        Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
                "Title %STARTSWITH '" _ pInfo.filters("Title") _ "'"
    }

    Set sql = "SELECT " _ tSELECT _ " FROM " _ tFROM
    Set:tWHERE'="" sql = sql _ " WHERE " _tWHERE
    Set:tORDERBY'="" sql =
       sql _ " ORDER BY " _tORDERBY _ $SELECT(tSORTORDER="desc":" desc",1:"")

    Set tRS = ##class(%ResultSet).%New()
    Set tSC = tRS.Prepare(sql)
    Set pInfo.queryText = sql

    Quit tRS
}

QueryInfo Properties

The following table describes the properties on the %ZEN.Auxiliary.QueryInfoOpens in a new tab object that appears in the signature for both callback methods.

Like tablePane, the dataCombo, dataListBox, and repeatingGroup components can also use callbacks to generate a component from a %ResultSetOpens in a new tab. Some of the properties in the QueryInfo object apply only to tablePane queries. dataCombo, dataListBox, and repeatingGroup ignore any table-only properties, including those for columns, filters, and sorting.

Only tablePane and dataCombo support the queryText property.

QueryInfo Properties

Property	Description
columnExpression	The colExpression values from each <column> in the <tablePane>. columnExpression organizes these values as a multidimensional array subscripted by <column> colName.
columns	The colName values from each <column> in the <tablePane>. columns organizes these values as a multidimensional array subscripted by column number (1–based).
filterOps	The filterOp values from each <column> in the <tablePane>. filterOps organizes these values as a multidimensional array subscripted by <column> colName.
filters	The filterValue values from each <column> in the <tablePane>. filters organizes these values as a multidimensional array subscripted by <column> colName.
filterTypes	The filterType values from each <column> in the <tablePane>. filterTypes organizes these values as a multidimensional array subscripted by <column> colName.
groupByClause	The groupByClause value for the <tablePane>, if supplied.
orderByClause	The orderByClause value for the <tablePane>, if supplied.
parms	Multidimensional array, subscripted by parameter number (1–based). This array contains any input values provided by <parameter> elements within the <tablePane>.
queryExecuted	Set this property to true in the method identified by OnCreateResultSet, to indicate that the newly created %ResultSetOpens in a new tab has already been executed and you do not want the method identified by OnExecuteResultSet to be called. The default is false.
queryText	The method identified by OnCreateResultSet can set this value to the actual query text, to be displayed if the showQuery value is true.
rowCount	If this value is set by the callback, upon return the rowCount property contains the number of rows returned by the query. After the query is executed, rowCount could be different from rows. Note that rowCount is a string, and not numeric, as its value might be "" or "100+". Any number of rows greater than 100 is represented as "100+". When testing rowCount from JavaScript, if you want to convert to a numeric value use parseInt for base 10: rowCount = parseInt(rowCount,10);
rows	The number of rows requested. For tables, this is the maxRows value.
sortColumn	The colName of the current sort column selected by the user.
sortOrder	The table’s current sort order (usually determined by user clicks) such as "asc" or "desc".
tableName	The <tablePane> tableName value.
whereClause	The whereClause value for the <tablePane>, if supplied.

Query Parameters

When you are working with SQL queries to generate the data for a Zen table, you sometimes need to provide values for query input parameters, defined as ? characters within the query. To do this, use <parameter> elements within the <tablePane> element. <radioSet>, <select>, <dataListBox>, <dataCombo>, <repeatingGroup>, and <multiSelectSet> can also contain <parameter> elements to support queries.

When you supply a query directly, as with a sql attribute, each <parameter> element substitutes for one ? in the query syntax, in order from left to right, even if the values are the same. For example:

<tablePane id="table"
           sql="SELECT ID,Name FROM MyApp.Employees
                WHERE Name %STARTSWITH ? AND 
                ((Salary &lt; ?) OR (TotalCompensation &lt; ?)) 
                ORDER BY Name"
           >
     <parameter value="Z"/>
     <parameter value="100000"/>
     <parameter value="100000"/>
</tablePane>

The “Data Sources” section in this chapter provides several other examples of how to use the <parameter> element, including the following class query example. Here each <parameter> element substitutes for one argument in the class query:

<tablePane id="table"
           queryClass="MyApp.Employee"
           queryName="ListEmployees">
    <parameter value="Sales"/>
    <parameter value="NEW YORK"/>
</tablePane>

When you work with %ZEN.Component.tablePaneOpens in a new tab programmatically, If you are using one of the classes <radioSet>, <select>, or <multiSelectSet>, which do not implement the setProperty, you must first set an id for the parameter:

<parameter value="Sales" id="param1"/>

The following example changes the value of the first parameter to Finance, re-executes the query on the server, and updates the contents of the tablePane to display the new results:

 ClientMethod changeParams() [ Language = javascript ]
 {
     // find the tablePane component
     var table = zenPage.getComponentById('table');
     var param1 = zenPage.getComponentById("p1");
     param1.value='Finance';
     table.executeQuery();
 }

Table Columns

The “Data Sources” section in this chapter explains that a <tablePane> draws an HTML table based on an SQL query. The table displays each row in the query resultset as a table row. A <tablePane> may also contain one or more <column> elements. <column> elements select which of the columns in the query resultset to display, and specify layout, style, and behavior for each column.

<tablePane> has a showRowSelector attribute which is true by default. If showRowSelector is true, the table displays an extra column at far left. This column appears empty when the table first displays. The purpose of this column is to indicate which rows are selected when the user selects them. If you want to suppress this column in your <tablePane>, set showRowSelector to false.

The “Generating an SQL Query” section includes the following example of how <column> elements can generate a table:

<tablePane id="table"
    tableName="MyApp.Employee">
    <column colName="ID" />
    <column colName="Name"/>
    <column colName="Title" style="color: blue;"/>
</tablePane>

The <column> element is the XML projection of the %ZEN.Auxiliary.columnOpens in a new tab class. <column> supports the general-purpose attributes described in the following table.

<column> also provides attributes that support dynamic filtering and linking for Zen table columns. Later topics describe these special-purpose <column> attributes:

• “Column Filters”

• “Column Links”

Finally, if you wish column layout to respond dynamically to user selections, the <tablePane> provides attributes that facilitate this for all columns in the table. See these sections:

• “Sorting Tables”

• “Selecting Rows and Columns”

When you work with %ZEN.Component.tablePaneOpens in a new tab programmatically, you work with <column> elements as members of the tablePane columns property, a list collection of %ZEN.Auxiliary.columnOpens in a new tab objects. Each <column> in the <tablePane> becomes a member of the columns collection in tablePane, associated with its ordinal position: 1, 2, 3, etc.

OnDrawCell

The OnDrawCell attribute provides the name of a server-side callback method in the Zen page class. This method injects HTML content into cells in the column using &html<> syntax or WRITE commands. Zen invokes this method whenever it draws the column, automatically passing it the following parameters:

• A pointer to the <tablePane> object.

• A string that gives the name of the SQL data column that this <column> is associated with.

• The seed attribute value from the <column>.

The callback must return a %StatusOpens in a new tab data type. The following is a valid method signature:

Method DrawYesNo(pTable As %ZEN.Component.tablePane,
     pName As %String,
     pSeed As %String) As %Status
{ }

To use the above method as the callback, the developer would set OnDrawCell="DrawYesNo" in the <column> statement:

<column colName="WorkDone" header="Complete?"
     OnDrawCell="DrawYesNo"  />

The following OnDrawCell callback method interprets a Boolean value (1 or 0) to display the string Yes or No in the <tablePane> column.

Method DrawYesNo(pTable As %ZEN.Component.tablePane,
     pName As %String,
     pSeed As %String) As %Status
{
  If %query(pName)
  {
    Write $$$Text("Yes")
  }
  Else
  {
    Write $$$Text("No") 
  }
  Quit $$$OK
}

To retrieve the data value from the SQL column while inside your OnDrawCell callback method, use the %query function as shown in the code example above. %query is a function that takes one argument, a string that identifies the name of the SQL column. The signature of your OnDrawCell method provides this value automatically in the input parameter pName. Thus, the expression %query(pName) in your method resolves to the value contained in the SQL column that corresponds to this <tablePane> <column>.

The example tests to see if the expression %query(pName) is non-zero. If so, it places the word Yes in the <tablePane> column; otherwise it places the word No in the <tablePane> column.

Using the %query function in an OnDrawCell callback method is not the same as using the %query special variable in Zen runtime expressions. For information and examples using the %query special variable, with dot syntax, see the sections “Zen Special Variables” and “Zen Runtime Expressions” in the book Developing Zen Applications.

Table Style

<tablePane> offers the following attributes to control the general style of the table.

Conditional Style for Rows or Cells

A <tablePane> may contain one or more <condition> elements. Each <condition> is a simple expression, based on the values of a given row, that controls the style of the row or of an individual cell within the row. For example:

<tablePane id="table"
    sql="SELECT Name,Home_State FROM MyApp.Employee">
    <condition colName="Name"
               predicate="STARTSWITH"
               value="A"
               rowStyle="background: plum;"/>
</tablePane>

In the above example, every row in which the value of the Name column starts with “A” is displayed with a plum background.

Typically, the conditional style mechanism is used to highlight rows or cells containing special values (such as out-of-range or error cases). Adding conditions does increase the amount of processing needed to display a table, so use them sparingly.

The <condition> element supports the following attributes:

When a table is displayed, all <condition> elements within the <tablePane> are evaluated individually for each row in the table. If a <condition> evaluates true, then the rowStyle or cellStyle for the condition is applied to the row or cell, respectively.

The <condition> predicate attribute may have the following values.

When you work with %ZEN.Component.tablePaneOpens in a new tab programmatically, you work with <condition> elements as members of the tablePane conditions property, a list collection of %ZEN.Auxiliary.conditionOpens in a new tab objects. Each <condition> in the <tablePane> becomes a member of the conditions collection in tablePane, associated with its ordinal position: 1, 2, 3, etc.

Snapshot Mode

A <tablePane> can operate in snapshot mode. In this mode, Zen runs the table query once and copies these results to a temporary location on the server. Subsequent screen refresh operations display data from this temporary location, rather than resubmitting the query. Zen automatically manages the creation and lifecycle of the temporary snapshot data. Snapshot mode is particularly useful for working with multipage tables. Note that refreshRequired has no effect when you are using snapshot mode.

The <tablePane> element supports the following attributes for snapshot mode.

Any of the query mechanisms described in this chapter can be used with snapshot or direct (non-snapshot) mode. The following example specifies an SQL query to be used in snapshot mode:

<tablePane id="table"
    sql="SELECT Name,Home_State FROM MyApp.Employee"
    useSnapshot="true"
    pageSize="25"
/>

The following %ZEN.Component.tablePaneOpens in a new tab properties are not available as XML attributes in the <tablePane> definition, but they can be useful for working with snapshot tables once the page has been created.

You can also programmatically adjust the values for useSnapshot and pageSize that were originally set by <tablePane> in XData Contents.

Column Filters

A Zen table can create a “filter” to place above the header for any column. A filter is a simple box with an input field where a user can enter one or more search criteria. When the user submits these changes, the query associated with the <tablePane> is re-executed using the new criteria. Zen updates the table and nothing else on the page changes.

Filtering works only if the <tablePane> is using an automatically generated SQL statement or an OnCreateResultSet callback, and the callback generates the appropriate WHERE logic to implement the data filtering. When your table uses a generated SQL query, your page class can gather what the user enters; format it appropriately into the %ZEN.Component.tablePaneOpens in a new tab properties groupByClause, orderByClause, and whereClause; then re-execute the table query.

The <column> element offers the following attributes for filters.

Zen invokes the OnDrawFilter method when it draws the column, but only if the value of filterType is "custom" at that time. Zen automatically passes the method the following parameters:

• %ZEN.Component.tablePaneOpens in a new tab — the <tablePane> object

• %StringOpens in a new tab — the colName value from the <column>

• %ZEN.Auxiliary.columnOpens in a new tab — the <column> object

The callback must return a %StatusOpens in a new tab data type. The following is a valid method signature:

Method DrawFil(pTable As %ZEN.Component.tablePane,
               pName As %String,
               pColinfo As %ZEN.Auxiliary.column)
               As %Status

{ }

To use the above method as the callback, the developer would set OnDrawFilter="DrawFil" for the <column>.

The following sample <tablePane> generates an SQL statement that displays the Name and Department of employees:

<tablePane id="table"
           useSnapshot="true"
           tableName="MyApp.Employee">
    <column colName="ID" hidden="true"/>
    <column colName="Name" filterType="text" />
    <column colName="Department"
            filterType="enum"
            filterEnum="Sales,Accounting,Marketing"
            filterOp="=" />
</tablePane>

This example uses the <column> filterType attribute to specify that the Name column should display a column filter (“text” indicates that this filter displays a box in which the user may type text). If the user enters a value in the box (such as “A”) and presses Enter, the table is updated to only show rows where the Name column starts with “A”. (If the <column> does not specify a filterOp value, the default matching operation is %STARTSWITH.)

For the Department column the example displays a more sophisticated filter: a combo box showing 3 possible values. To do this, it sets the <column> filterType to “enum” and sets filterEnum to a comma-separated list of possible values. It also specifies that an exact match is required, by setting the filterOp value to "=".

A <tablePane> has filters active and enabled by default. You do not need to supply any <tablePane> attributes to enable filtering. However, should you want to override the default settings, <tablePane> offers the following attributes that control filtering for the table as a whole, not just for individual columns.

Column Links

Columns within a Zen table can display links, such as a link that takes the user to another page to edit the details of the object displayed within the current row. This link can either be displayed within a column that contains a data value (in this case, the data value is displayed as a link), or as an extra column in the table that contains the link.

The <column> element offers the following attributes for links.

The following is an example of using JavaScript code to further process the <column> link value before using it to go to another page:

<tablePane id="table"
    sql="SELECT TOP 100 ID,Item,Price FROM MyApp.Inventory ORDER BY Price">
    <column colName="ID" hidden="true"/>
    <column colName="Item"
            link="MyApp.ItemEdit.cls?ID=#(%query.ID)#"
            linkCaption="View information on this item."
    />
    <column link="javascript:zenPage.addToCart('#(%query.ID)#');"
            linkCaption="Add to cart"
            linkConfirm="Do you wish to add this item to your cart?"
    />
</tablePane>

This example does the following:

1. The <tablePane> sql value specifies that this table displays information about the top 100 items in the MyApp.Inventory table ordered by price.

2. The <tablePane> needs the value of the “ID” column (as part of the links) but there is no need to display this value. Therefore, the <column> hidden value is true.

3. The <tablePane> needs the “Item” column to contain a link to a page that displays information about a specific item. Therefore, the <column> link value defines this link. The <column> linkCaption value defines a tooltip message that is displayed when the user moves the mouse over this link.

4. The <tablePane> defines an extra column (with no data displayed in it) that contains an “Add to cart” link. This link invokes a client-side addToCart method when the user clicks on it. The linkConfirm property specifies a confirmation message displayed to the user before executing the link.

The two link values used within this <tablePane> example make use of the Zen expression syntax to include the value of row-specific data within the link. See the section “Zen Runtime Expressions” in the “Zen Pages” chapter of Developing Zen Applications. The following expression refers to the ID column within the current row of the table:

#(%query.ID)#

For the second of the two link examples to work, the client-side addToCart method must compose the URI and invoke the new page. Using a client-side method is important when you need to encode special characters that may appear in the text value returned by the query; for example:

ClientMethod addToCart(identifier) [Language = javascript]
{
  var page = "MyApp.AddToCart.cls?ID=" + encodeURIComponent(identifier);
  this.gotoPage(page);
  return;
}

User Interactions

Zen tables provide built-in mechanisms to support basic user interactions such as navigating pages, sorting columns, and selecting rows in a table.

Navigation Buttons

The <tableNavigator> component automatically displays a set of buttons for moving through the pages of a <tablePane>. The <tableNavigatorBar> has identical syntax, but displays extra buttons to help users navigate large, multipage tables.

To use either component, place it anywhere on the same page as a <tablePane> and set its tablePaneId attribute value to match the id value from the <tablePane>. For example:

<pane id="tPane">
  <tablePane id="myTable"
             tableName="MyApp.Employee">
    <column colName="ID" hidden="true"/>
    <column colName="Name"/>
  </tablePane>
  <tableNavigatorBar tablePaneId="myTable" />
</pane>

If a <tableNavigator> or <tableNavigatorBar> is placed within a composite element, the corresponding <tablePane> must be placed within the same composite element.

Table Refresh

When you refresh a table, only the table refreshes. It is not necessary for the entire Zen page to refresh itself in order to refresh a table.

Typically, Zen refreshes the visible contents of the table automatically as needed. When you work with tables programmatically, you can also explicitly refresh table contents. The techniques are as follows:

• Call the %ResetQuery method of the %ZEN.Component.tablePaneOpens in a new tab from a server-side method. This forces the tablePane to re-execute its query.

• Call the executeQuery method of the %ZEN.Component.tablePaneOpens in a new tab. This causes the data query to be re-executed and updates the visible contents of the table to reflect the current values of tablePane properties.

Note that calling %ResetQuery has no effect when you are using snapshot mode.

Table Touchups

Any time you set an attribute value for <tablePane> in XData Contents, the corresponding property in the tablePane object automatically acquires this value. This might be just enough programming for your purposes. Nevetheless, %ZEN.Component.tablePaneOpens in a new tab offers many more opportunities for programmatic interaction on the client or server sides.