Xafari Object Formatter. Learn More
Formatted Output
To specify additional format use standard .NET formatter's notation:
Formatting notation are processed by the special Formatter service. For working Formatter requires to specify the context object as a parameter.
The '=' character at the beginning of the line means that the text is a format for Formatter. Everything that immediately follows the '=' character, will be formatted. Braces enclose the portion of text where to get the formatted value. To display the '{' and '}' characters , use '{{' and '}}' combinations respectively. Formatter divides the entire original string into parts, selects those that are to be formatted, and consistently runs formatting algorithm for each part.
0: is a mandatory part, it tells the Formatter that the 0th parameter will be used for this format as a context. This Formatter receives only one object (the ccontext) as a parameter. So 0 is always used. After the colon follows the actual format notation, which may consist of two parts:
The mandatory part. It specifies a navigation path through the objects' properties, which allows to achieve the desired object and format it. Formatter knows how to navigate the properties of the standard object types, reference properties and collection items (see Collection Items Navigation below). There is also a modifiable list of global properties, called parameters, which can also be used for navigation (See Parameters Navigation below). Let examine an example:
As the context is the Props object (i.e. 0). Starting from the Props object (initial context) first, Formatter will navigate to its Document property, then Formatter will get CreationDate property of the Document object. Obtained a target object will be displayed according to the specified format.
Optional part. It is a way of the formatting of the destination object. If this part is not specified, it will use the default format defined for each data type. In our example, the format 'yyyy' is specified. This means that the target object is of date type and will apply such format, which will display a Year using 4 characters.
Note:
The ".", ",", ":", "[", "]", "{", "}" symbols in a format string are interpreted as format specifiers. At the same time, there may be situations where these characters can be required as literals. For instance, the character should be included in the result string unchanged, or it is required to specify the index, format, the name of property. The following table contains the relevant substitutes, which prevent a character from being interpreted as a format specifier:
Literal |
Substitute |
. |
.. |
, |
,, |
: |
:: |
[ |
[[ |
] |
]] |
{ |
{{ |
} |
}} |
Refer to the following topics for more information about the supported formats:
- Formatting Types
- Standard Numeric Format Strings
- Custom Numeric Format Strings
- Standard Date and Time Format Strings
- Custom Date and Time Format Strings
- Enumeration Format Strings
Collection Items Navigation
To use this feature, the collection must implement one of the following interfaces: ICalculatedParameter, IDictionary, IList, IEnumerable. To navigate through the collection items use the following notation:
- example
{0:<property_or_collection_item>(.<property_or_collection_item>),<formatting>}
<property_or_collection_item> :- <property> | [<index>] | [value]
<index> :- <ordinal number> | <text>
In case ICalculatedParameter [value] will be processed. The value of the parameter will be calculated using ObjectFormatter.
In the case of the IDictionary object will be selected by <index> key where <index> is considered a string.
In the case of the IList first, Formatter tries to convert IList to a list of named objects (INameSupport interface) and return the object with the <index> name. If this fails, <index> is treated as a number, and the element with the specified sequence number will be returned.
For the IEnumerable interface <index> is treated as a number, and the element with the specified sequence number will be returned.
Parameters Navigation
To navigate through the collection items use the following notation:
- example
{0:@<parameter_name>.<property_or_collection_item>(.<property_or_collection_item>),<formatting>}
The list of parameters can be expanded as needed. By default, it contains:
- CurrentDate
- CurrentDateTime
- CurrentDatePlus1Day
- CurrentDatePlus2Days
- CurrentDatePlus3Days
- WeekAgo
- CurrenUserID
Expressions
There is an alternative method of navigation, it is Expressions. It provides additional functions to calculate formatted values, including conditional expressions.
To use Expressions, specify the expression string in a double quotes.
Notation:
Example:
See also Examples topic.