Custom Formatting

Custom formatting may be required when a value displayed on an application page is not in the required format. A custom formatter might be used to pad values with extra characters, so that they appear to be the same length; insert a currency symbol into money values; format numeric values without grouping separator characters; or even take a date value based on the Gregorian calendar and format it after converting it to another calendar system.

  1. Identify an existing converter plug-in class that you want to customize. It will most likely be the converter that is already configured for the domain in question or inherited by it from an ancestor domain.
  2. Create a new sub-class of the relevant converter plug-in and override the format method.
  3. In the implementation of the method, you can perform some processing before or after invoking the super-class's method of the same name, or implement the formatting code from scratch.
  4. Configure your new plug-in for the relevant domains.

The calendar scenario is somewhat unrealistic because the date selector widget would not be compatible, but inserting a currency symbol, or an analogous operation, is something that you may want to do. If multiple currencies are supported, then domains such as US_DOLLAR_AMOUNT or EURO_AMOUNT might be used to represent values in each currency (though the out-of-the-box Cúram application uses a different scheme for representing money values in different currencies). Custom converter plug-ins may then be written to format money values for each of these domains by adding the appropriate currency symbol.

This example shows how a converter plug-in can be written that takes a money value and prefixes the formatted numeric value with a dollar symbol. The out-of-the-box Cúram application comes with a converter plug-in that formats money values, but without any currency symbol, so you can reuse its format operation to simplify the implementation.

Figure 1. Custom Formatting for Currency Values
/**
 * Converter that supports the use of a dollar symbol for
 * money values.
 */
public class USDollarConverter
       extends SvrMoneyConverter {
  public String format(Object data)
         throws ConversionException {
    return "$" + super.format(data);
  }
}

The implementation is very trivial: the super-class does all the work and returns a nicely formatted money value; the customization just adds the dollar symbol.

The configuration file for this customization is shown below. The file might also include entries for other customizations that have been made. As the comparator and default value plug-ins have not been customized, they do not appear in the configuration. These plug-ins will be inherited from the ancestors of the US_DOLLAR_AMOUNT domain (probably the SVR_MONEY domain).

Figure 2. Configuration for Custom Formatting
<dc:domains xmlns:dc="http://www.curamsoftware.com/curam/util/common/domain-config">
    <dc:plug-in name="converter"
                class="custom.USDollarConverter"/>
  </dc:domain>
</dc:domains>

Values displayed on an application page (or even those passed behind the scenes in hidden page connections) may be submitted back to the web application. If you write a formatter that inserts a currency symbol, or you allow users to insert currency symbols in values that they type in, then you will need to accommodate such values in the parse operation. The next section will demonstrate the custom parse operation required to match this custom format operation.

Another common need for custom formatting is to format integer values without grouping separator characters. For example, an integer value that represents the year "2005" should probably be formatted as "2005" and not "2,005". If the year value is represented by the YEAR_VALUE domain and that domain is derived from the SVR_INT16 domain, the custom format operation would look like this:

Figure 3. Custom Formatting without Grouping
/**
 * Converter that formats year values without adding grouping
 * separator characters.
 */
public class YearValueConverter
       extends SvrInt16Converter {
  public String format(Object data)
         throws ConversionException {
    return data.toString();
  }
}

This converter overrides the format method of the SvrInt16Converter class and simply converts the data object (a java.lang.Short) to a string. Unlike the routines used by the super-class, the toString method will not do any locale-aware formatting or add any grouping separator characters. The parse method is not overridden, so values that are entered with or without grouping separator characters will be accepted. This converter is configured in the same way that the currency symbol converter was configured.

Parent topic: Customization Guidelines