Data Formatters

Overview

Requires Platform 4.2+

A formatter translates data coming from a data source for display. For example, a formatter might transform the number object 1123.8 into the string “$1,123.80” for display by the user interface. Each binding has a chain of formatters that data passes through.

Declaring formatters is similar to declaring data sources.  The following example shows a formatter:

<formatter id=”customers” 
 class=”com.nexaweb.plugin.data.formatter.MessageFormatter” 
 format="There are {0} customers in the database"/>

The following table describes the ways you can define your own formatters: 

For more information on defining your own formatters, see Creating a Formatter.

In addition, Nexaweb provides the following formatter tags for transforming data for display in a UI:

• messageFormatter
• decimalFormatter
• dateFormatter
• currencyFormatter
• stringToDateFormatter
• formatterChain

For more information on pre-defined formatters, see Supplied Tags.

Note: Nexaweb does not provide validation to suit all needs.  For example, Nexaweb does not provide formatters for state abbreviations, postal codes, phone numbers, and so forth.  However, Nexaweb provides a formatter tag to enable you to easily create formatters that provide these features.

Supplied Formatter Tags

Nexaweb provides the formatter tags described on this page.

formatter Tag

Use the formatter tag to declare a formatter class you create using the com.nexaweb.plugin.data.formatter API.

The formatter tag includes the following attributes:

In addition to using the formatter tag to declare your own formatter class, you can also create your own tag that uses different attributes.

messageFormatter Tag

Use the messageFormatter tag, based on java.text.message format, to specify the pattern and format to use for string messages.

The messageFormatter tag includes the following attributes:

Output

The messageFormatter tag always outputs a java.lang.String object, since the class for this formatter uses the java.text.MessageFormat class.

Input

The following table lists the input types allowed for each format string (since this class uses the java.text.MessageFormat class, the specified format string dictates the input accepted): 

Note: In 1.4+ JVMs, Nexaweb uses the getFormatsByArgumentIndex() method to accept a string object anywhere a number is expected as long as that string can be parsed into a Number.  In addition, Newxaweb accepts strings anywhere it expects a date as long as Long.parseLong(String) or default DateTime instance can parse that string.

In JVM 1.3 and below environments, Nexaweb cannot reliably convert arguments to the expected types because the MessageFormat API does not provide enough information.  Nexaweb attempts to convert arguments when formatting fails with the original arguments but this works only in some cases (that is,  where getFormats() and getFormatsByArgumentIndex() would return the same format array).  For example, for the following format string: My string with a date: {0,date}, a number {1,number} and some string {2} both getFormats() and getFormatsByArgumentIndex() return the same result.

However these methods would not return the same value given the following format string: My string with some string {2}, a number {1,number} and a date: {0,date}

For both format strings, getFormatsByArgumentIndex() would return the same array of formats: [DateFormat,NumberFormat,null] (null stands for no format or just String). However getFormats() would return [DateFormat,NumberFormat,null] in the first example and [null, NumberFormat,DateFormat] in the second one. Thus, for best result in JVM 1.3 and below environments, pass the correct argument types to the MessageFormatter.

currencyFormatter Tag

Available for Nexaweb Java applications only.

Use the currentyFormatter tag, based on java.text.NumberFormat, to create currency strings from numbers.

The currentyFormatter tag includes the following attributes:

decimalFormatter Tag

Use the decimalFormatter tag, based on java.text.DecimalFormat, to create decimal format strings.

The decimalFormatter tag includes the following attributes:

dateFormatter Tag

Available for Nexaweb Java applications only.

Use the dateFormatter tag, based on java.text.DateFormat, to create dates from a string.

The dateFormatter tag includes the following attributes:

stringToDateFormatter Tag

Available for Nexaweb Java applications only.

Use the stringToDateFormatter tag to create dates from a string without any text style formatting.

The stringToDateFormatter tag includes the following attributes:

formatterChain Tag

The formatterChain tag defines a chain of formatters where the output of one formatter becomes the input to the next formatter in the chain. You can use this tag anywhere you can use a regular format.  In the following example of a fomatter chain, myStringToDateFormatter, myDateFormatter and myMessageFormatter represent id attributes of the previously defined formatters:

<formatterChain id="myChain">
   <formatterReference formatter="myStringToDateFormatter/>
   <formatterReference formatter="myDateFormatter" />
   <formatterReference formatter="myMessageFormatter" />
</formatterChain>

The formatterChain tag uses the ID attribute only.  The ID tag uniquely identifies this messageFormatter using a system wide unique value. The formatterChain tag can use the formatterReference element as a child.

Creating a Formatter

Defining Modules to Format Data

As part of the data binding framework, Nexaweb provides you with the ability to implement your own functionality to transform data for presentation in the UI.  For example, you can implement your own formatter to turn a custom object returned from a data source into an appropriate String.  In order to implement the functionality of a formatter, you must implement the required interface (com.nexaweb.plugin.data.formatter.Formatter) as defined in the API section.

Nexaweb ships with the predefined formatter tag. You can use this tag to utilize the interface that you implement by specifying your implementation's class as the class attribute of the formatter tag.

Formatter tag

The most basic formatter tag, formatter, simply defines a formatter with its implementing class and its ID.

 In addition, developers may elect to create their own formatter tag definitions.