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.

Attribute	Description
cellTitle	Text specifying the tooltip message for any cell within the column. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.captionOpens in a new tab. See “Zen Attribute Data Types.”
colExpression	If the table is automatically constructing an SQL query, this is the SQL expression used to get the value of this column. For example: colExpression="Customer->Name". Does not support aliasing. When using colExpression, you must also specify colName.
colName	The name of the SQL data column that this column is associated with. For more information, see colName.
disableSort	If true, disables sorting this column when the user clicks on the column header. If false, enables sorting. The default is for column sorting to be enabled in each column as long as the useSnapshot attribute for the containing <tablePane> is set to true.
header	Text specifying the column header. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.captionOpens in a new tab. See “Zen Attribute Data Types.” The header value can be a literal string, or it can contain a Zen #()# runtime expression.
hidden	If true, this column is not be displayed. The default is false. hidden has the underlying data type %ZEN.Datatype.booleanOpens in a new tab. See “Zen Attribute Data Types.” The hidden value can be a literal string, or it can contain a Zen #()# runtime expression.
OnDrawCell	Name of a server-side callback method in the Zen page class. For more information see OnDrawCell.
seed	Allows you to pass some arbitrary value to the OnDrawCell callback.
style	CSS style value to be applied to the cells (HTML <td> elements) within this column. For example: "color: red;" The style value can be a literal string, or it can contain a Zen #()# runtime expression.
title	Text specifying the tooltip displayed when the user moves the mouse over the column header. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.booleanOpens in a new tab. See “Zen Attribute Data Types.”
width	Usually, the HTML style value for Zen tables is "fixed". This means that each column has a specific width value in the generated HTML page. Zen determines these values as follows: You can specify a width value for any column. If you do not specify a width for some columns, Zen assigns a width that is proportional to the size of the contents of that column (relative to other columns in the table). If you do not supply a width value for any column in the table, Zen uses an HTML style value of "auto" for the entire table. The width value can be a literal string, or it can contain a Zen #()# runtime expression.

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

colName

The colName attribute provides the name of the SQL data column that this column is associated with. The colName value can be a literal string, or it can contain a Zen #()# runtime expression.

If any colName values in the <tablePane> are duplicates, the second column displays as “(duplicate) colName” to indicate that unless the second column is renamed, the <tablePane> may display unexpected behavior.

If no colName is specified for a column, the column is displayed without a data value. Typically this technique is used to display a link action in a row.

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.