Formatting Concepts

Format objects are used to control how information is converted to and from strings. Formatting occurs for two reasons:
  • System formats - string representation of a value that is never displayed to a user and used internally by the application. For example, the ID string of a model object.
  • Display formats - string representation of a value that is mean to be displayed to or entered by a user. For example, a "mm/dd/yyyy" format of a date.

All formats are represented by the ExoWeb.Model.Format class which has convert and convertBack operations. Note, these are the same names and signatures used by Microsoft AJAX's Sys.Binding class.

How formatting fits in

Formats appear in the following places in ExoWeb:
  • <type>.formats (where formats are declared)
    • $system - default system format of <type>
    • $display - default display format of <type>
  • Property metadata
    • format - display format which overrides the default display format for the properties type

Adapter (@ markup extension)
displayValue - Display-formatted version of the bound property
systemValue - System-formatted version of the bound property

displayFormat - Name of the format to use by the displayValue property. Overrides the default display format.
systemFormat - Name of the format to use by the systemValue property. Overrides the default system format.

Adapter option
systemValue - System format of the option
displayValue - Display format of the option

Built-in formats
Formatting occurs automatically in many cases. There are some built in formats for Date, Boolean and String objects, such as ShortDate for dates, YesNo for bool's, and PhoneNumber for strings.

TIP: An easy way to see what formats are defined for a type is to inspect <type>.formats in a debugger.

Defining custom formats
To define a custom format for a type, simply add it to the types format object as a type extension.

For example, this is how you can create a new "FullName" format for the Employee class:

$extend("Employee", function(type) {
type.formats.FullName= new ExoWeb.Model.Format({
convert: function(val) {
return val.get_FirstName() + " " + val.get_LastName();

Or, you can shorten the above code by using Format.fromTemplate:
$extend("Employee", function(type) {
type.formats.FullName = ExoWeb.Model.Format.fromTemplate("{FirstName} {LastName}");

Besides the covert function passed to the Format constructor, a convertBack function can also be passed.

To change the formatting of a built-in Javascript type, such as Date, don't use $extend(). Instead set the format directly:

Date.formats.MyFormat = new ExoWeb.Model.Format(...);

Last edited Apr 16, 2010 at 9:40 PM by mattheyan, version 2


No comments yet.