ExoWeb Formatting Changes
Jamie Thomas
Big changes are coming to ExoWeb over the next week. One significant breaking change is the introduction of a new approach for formatting values. The previous approach using named formats like ShortDate, $display, etc. has been completely replaced by format specifier strings. You are already very familiar with these since they are part of the .NET framework, but as you may expect, ExoWeb throws in a few nice surprises. This change is a positive change in terms of capabilities and overall utility, but was necessitated by the recent addition of server-side rendering into the ExoWeb stack, which made the JavaScript-based named formats difficult to replicate on the server.
See ExoWeb Formatting to view the updated documentation online.
Introduction
ExoWeb builds on the formatting capabilities of ExoGraph by leveraging format specifiers to format and localize all types of data. Every property in the type model has an optional format , which is a simple string expression describing how to format the value of the property. These formats are automatically used when binding via adapters in the view. Additionally, when using binding expressions, an optional format may be specified to override the default formatting for a property in a specific situation.
Number and Date Formatting
For numbers and dates, ExoWeb supports the standard and custom format specifiers used in the .NET framework. For example, a date property intended to be just a date without a time component may have a default format of "d" in the model, which would cause the date to be formatted as M/d/yyyy in the en-us culture.
Movie: {
properties: {
Released: { type: "Date", format: "d" }
}
}
In this example, the client model type Movie has a property called Release that has a default format of "d", or the short date format. However, when displaying the movie release date on a page it may be desirable to just show the month and year of the release, since the specific day is not important. This can be done by specifying the format as part of the binding expression as follows:
<span>{# Released, format=Y}</span>
The format of "Y" in the binding expression forces the Month Year format to be used by ExoWeb in a culture appropriate way. Additionally, custom format specifiers may be used, such as "MMM 'YY" to display the date as Jan '12.
Boolean Formatting
Since the .NET framework does not support format specifiers for Boolean types, ExoGraph and ExoWeb fill the gap by providing a custom format specifier syntax for conditional values. The syntax has the form "true value;false value;null value" where the true, false, and null string values are separated by semicolons.
For example, to format at Boolean property as either Yes or No, the format specifier would be "Yes;No". The syntax also supports nullable Boolean values in the case where a true or false value has not been assigned, such as "Yes;No;Maybe" or "Yes;No;Don't Care", although this third value does not need to be included. If a value is not specified, an empty string is used.
Entity Formatting
Model types get special formatting treatment in ExoGraph and ExoWeb. ExoWeb supports the full instance formatting capabilities of ExoGraph both when rendering on the server and when rendering on the client. The is especially useful with views, where a binding expression can override the default formatting to display a value for an entity, such as:
<span>{# Movie, format=[Name] ([Released:yyyy])}</span>
In this example the movie Robin Hood, released on 5/14/2010 would be displayed as "Robin Hood (2010)". Additionally, if any property referenced in an expression will use the default model format unless it is overridden in the format expression, so if the format had just been "[Name] ([Released])" the result would have been "Robin Hood (5/14/2010)" because the default format in the model for the Released property is "d" or short date.
Also, formats for entities have the added benefit of knowing what paths are used to format an entity, such that bindings that depend on these values will automatically update when changes to the underlying properties occur. For example, if the Released property of Robin Hood was changed from 5/14/2010 to 7/12/2009, the above binding would immediately update because the binding knows that it is dependent on both the Name and Released properties of the Movie instance and updates automatically whenever these properties change.
In addition to specifying entity formats on properties and in binding expressions, default formats can be specified for entity types themselves, and inherited from base types. For example:
NamedItem: {
format: "[Name]",
properties: {
Name: { index: 0, type: "String" }
}
},
Movie: {
baseType: "NamedItem",
format: "[Name] ([Released:yyyy])",
properties: {
Released: { index: 3, type: "Date", format: "d" },
},
}
In this case the Movie type has a default format of "[Name] ([Released:yyyy])", which automatically applies to all model properties of type Movie that do not override this format. However, if Movie did not specify a format, it would have inherited the format "[Name]" from the NamedItem base type.