Content Formatting and Localization

The Matrix control supports three main mechanisms for formatting content:

• XSLT
• JavaScript
• Edit Masks

Many factors affect which approach to use, such as performance, developer skill set, and code maintenance.

XSLT

When using the XSLT approach to customize the data output, a cell value template can be specified for each column. The cell value template is effectively an XSL template that is under the control of the developer. This template receives the following parameters, which can be used by the developer to gain the necessary context to author the template (in addition to the implied CDF record context under which the template will execute).

To specify a custom template, call the setValueTemplate() method (jsxvaluetemplate) on the given column child. For example, the following xsl:template is a custom value template that inserts a dollar symbol ($) in front of the mapped attribute for the column. Notice the wildcard, {0}, which will be replaced with the value of the column's mapped path. This is then followed by the on-screen row number that the cell is a child of:

<xsl:template xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:\param name="jsx_row_number"/>
$<xsl:value-of select="{0}"/>
<xsl:value-of select="$jsx_row_number"/>
</xsl:template>

XSLT and Standard Value Templates

In addition to creating custom value templates, you have the option to use one of the standard value templates, which is a property of Matrix Column.

JavaScript

In addition to XSLT, JavaScript can be used to further format the output of the cell data. Using the JavaScript approach, the cell data is painted on-screen first, and then a function is notified that a given cell needs further formatting.

There are two ways to use JavaScript to format the output:

• Use column formats provided by the jsx3.gui.Matrix.ColumnFormat interface
• Use a function literal

ColumnFormat Interface

The simplest way to do this is to use one of the standard column formats provided by the jsx3.gui.Matrix.ColumnFormat interface.

To use the ColumnFormat interface, call the setFormatHandler() method on the given column instance, passing the given formatter as a string.

For example,

instance.setFormatHandler("@number,currency");

To create a custom formatter, create a static implementation of the MatrixFormatHandler class. For more information, see General Interface API Reference.

Function Literal

When even greater control is needed over the cell format, a function literal can be used with the same signature used by the Matrix.ColumnFormat interface. For example, the following function could be used to convert the given value to a localized currency format. Although this is the same as passing the Matrix.ColumnFormat.CURRENCY, it provides greater control by allowing you to use your own method for localizing the currency.

For example,

var s =
   function(element,cdfkey,matrix,matrixcolumn,rownumber,server) {
     var mf = new jsx3.util.MessageFormat("{0,number,currency}");
      element.innerHTML = mf.format(element.innerHTML);
   };
[instance].setFormatHandler(s.toString());

Edit Masks

An edit mask is any child of a Matrix Column in the DOM. Edit masks typically implement jsx3.gui.Form but can also be constructed from collections of objects. An edit mask allows the user to enter a value in a Matrix cell. User edits are persisted to the CDF data source of the Matrix.

There are two types of edit masks:

• Only visible when editing, such as a text box
• Always visible in every row, such as a checkbox or radio button

The edit masks in the Component Libraries palette include some of the following: Text Box, Text Area, Radio Button, Checkbox, and so on. More complex examples of creating edit masks using a Block and Dialog are also provided as prototypes in the Component Libraries palette.

Edit Masks and Matrix Model Events

Model events are an abstraction layer for native browser events. They translate events from the domain of the browser UI into events from the General Interface model domain. Model events are persistent in JSX serialization files and are thus a static binding from the UI definition to JavaScript code.
There are three Matrix model events that affect edit masks:

• Before Edit
• After Edit
• After Commit

The Before Edit and After Edit events are vetoable model events. A vetoable model event is published before an action is executed by the system. If the vetoable event evaluates to false, the system doesn't complete the action.

You can add your own custom logic to these events in the Events Editor palette. After adding a Matrix component to your application, select the Matrix component in the Component Hierarchy palette and look for these events in the Events Editor palette. For documentation on context variables, hover the mouse over the event name in the Events Editor palette.

Before Edit

The Before Edit event is only published for edit masks that are visible when editing, such as text boxes.

The Before Edit event is a vetoable event that fires before a cell edit session begins. Whenever a user focuses in a Matrix cell, the Before Edit event executes. If the Before Edit event is vetoed, the edit session never starts. For example, the Matrix Grid prototype has this JavaScript statement in the Before Edit event:

jsx3.log('EVENT: (jsxbeforeedit). Record: ' + strRECORDID);

When a user selects a cell in the Name column of this Grid prototype, this JavaScript statement causes the CDF record ID of the cell to print to the System Log palette. For more information on context variables, such as strRECORDID, hover the mouse over the event name in the Events Editor palette.

Using Multiple Edit Masks

You can use multiple edit masks in a single column. For example, some cells might use text boxes, while other cells use drop-down lists. The Properties Editor palette in General Interface Builder is a good example of using multiple edit masks in a column.

To use multiple edit masks in a column:

1. Add all edit masks to use as children of the Matrix Column.
2. Write custom JavaScript logic in the Before Edit event to control under what conditions each mask is shown.

In the following code example, a Matrix Column has two children. Text box (0) is the first child and select box (1) is the second child. This JavaScript code causes the select box to be shown for any CDF record with an enum attribute. Otherwise, the text box mask displays.

if (this.getParent().getRecord(strRECORDID).enum)
   var retVal = {objMASK: this.getChild(1)};
else
   var retVal = {objMASK: this.getChild(0)};
retVal;

In the previous code example, this is the Matrix.Column context variable, the getParent() method returns the Matrix, and strRECORDID is a context parameter.

After Edit

The After Edit event is a vetoable event that fires after a user changes a value and moves focus to another cell, but before the edit is committed to the CDF data source. The After Edit event is useful for restricting, filtering, and verifying user input.

For example, entering the following JavaScript statement in the After Edit event in the Events Editor palette, would allow only user input starting with the letter i :

strNEWVALUE.indexOf("i") == 0

If a user types a word that doesn't begin with i, the event is vetoed.

After Commit

The After Commit event, a non-vetoable event, fires after an edit session is committed and the CDF is modified. It is safe to query the CDF document for the updated state using this event.

Rendering Combinations Best Practices

Follow these recommended rendering best practices for best rendering results:

• If using the Column Format property, use @empty for the Value Template property. Using this combination prevents a visible blink that occurs between the first and second rendering pass.
• For form elements that are always visible, use @empty for the Value Template property. Using @empty prevents the form element value from printing next to the edit mask. For example, for a checkbox, you want the checkbox to render, but you don't want the checkbox value rendered.
• For date columns, match the format used by the Date Picker edit mask with the Column Format.

For more information, see XSLT and Standard Value Templates and ColumnFormat Interface.