Format a Property Value
- 5 minutes to read
In this lesson, you will learn how to set a display format and an edit mask to a business class property. For this purpose, the Task.StartDate, Task.DueDate, Task.PercentCompleted and PhoneNumber.Number properties’ display format will be customized using the Model Editor.
Note
Before proceeding, take a moment to review the following lessons:
- Inherit from the Business Class Library Class (XPO/EF)
- Place an Action in a Different Location
Apply an Edit Mask and a Display Format to a DateTime Property Value
- Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl(DevExpress.Persistent.BaseImpl.EF) | Task | OwnMembers node and select the DueDate child node. To the right, you will see properties that represent the DueDate property’s settings.
Find the DisplayFormat property located under the Format category. Its default value is “{0:d}”. This mask corresponds to the short date pattern (e.g., “3/21/2014”). To use the long date pattern (e.g., “Friday, March 21, 2014”), set the DisplayFormat property to “{0:D}”. However, the long date pattern is inconvenient when typing the date manually. So, set the EditMask property value to “d”. This mask will be used when the DueDate property editor is focused.
Note
You can set the DisplayFormat property to “D” instead of “{0:D}”. These values set the same formatting in a WinForms application. However, note that the “D” value is not valid in an ASP.NET application. Use the “{0:<Format_Specifiers>}” syntax instead.
Select the StartDate child node. Set the DisplayFormat property to “{0:D}” and the EditMask to “d”.
Run the WinForms application. Invoke a detail form for the DemoTask class. You will see that the formatting of the StartDate and DueDate properties depends on the focus. When the Property Editor is focused, the EditMask is applied, and the property value is formatted according to the short date pattern (the “d” edit mask). When the Property Editor is not focused, the DisplayFormat is applied, and the property value is formatted according to the long date pattern (the “D” format specifier).
Run the ASP.NET application. Invoke a detail form for the DemoTask class. You will see that the DisplayFormat is applied, and the StartDate and DueDate property values are formatted according to the long date pattern (the “D” format specifier).
Click the Edit button to display the DemoTask object in Edit mode. You will see that the EditMask is applied, and the StartDate and DueDate property values are formatted according to the short date pattern (the “d” edit mask).
Note
Refer to the Mask Type: Date-time, Format Specifiers and Composite Formatting topics for details about formatting with masks in WinForms, and the Mask Types topic for formatting in ASP.NET. Note the differences in the use of angle brackets.
Apply the Display Format to an Integer Property Value
- Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl | Task | OwnMembers node and select the PercentCompleted child node. To the right, you will see properties that represent the PercentCompleted property settings.
Set the DisplayFormat property to “{0:N0}%”.
Run the application. Invoke a detail form for the DemoTask class. You will see that the PercentCompleted property value is displayed with the ‘%’ sign appended.
In a WinForms application:
In an ASP.NET application:
Since the EditMask was not specified, the ‘%’ sign is not appended when the editor is focused in a WinForms application. In an ASP.NET application, the ‘%’ sign is not appended when the Detail View is in Edit mode.
Apply the Edit Mask to a String Property Value
- Invoke the Model Editor for the MySolution.Module project. Navigate to the BOModel | DevExpress.Persistent.BaseImpl | PhoneNumber | OwnMembers node and select the Number child node. To the right, you will see properties that represent the Number property’s settings.
Set the EditMask property to “(000)000-0000”.
Note
- The EditMaskType property is set to Simple by default. However, you can use the simplified regular expression mask by setting this property to RegEx. In this instance, an appropriate regular expression for a phone number is “((\d\d\d))\d\d\d-\d\d-\d\d”. However, note that the RegEx edit mask type is currently supported in WinForms applications only.
- When the EditMask property is focused, the ellipsis button (
) is displayed to the right of the property value. You can click this button to invoke the Mask editor dialog, which helps you create and test a mask.
Run the WinForms or ASP.NET application. Invoke a detail form for the Contact class. Add a PhoneNumber object to it using the New Action that accompanies the PhoneNumbers collection. In the PhoneNumber Detail View, you will see that the Number property supports the specified mask.
The PhoneNumber Property Editor allows you to input digits at the positions specified by the ‘0’ metacharacters. The ‘(‘, ‘)’ and ‘-‘ characters cannot be removed, and their positions are fixed. As a result, end-users will not be allowed to type an incorrectly formatted phone number.
The ‘(‘, ‘)’ and ‘-‘ characters are saved within the property value, so you do not need to specify the DisplayFormat to display the parentheses and hyphen when the Property Editor is not focused, or the property value is not editable.
Refer to the Mask Type: Simple topic for details.
Note
The EditMask only prompts a user. It cannot prohibit saving the incorrect value (e.g., when a user does not fill all the required digits in a phone number). Use the Validation Module to configure strict rules.
A custom formatting example is provided in the PropertyEditors | Custom Formatting Properties section of the FeatureCenter demo. By default, the FeatureCenter application is installed in %PUBLIC%\Documents\DevExpress Demos 18.2\Components\eXpressApp Framework\FeatureCenter.
Tip
You can specify default formatting for all properties of a given type. In a platform-specific project, use IModelRegisteredPropertyEditor.DefaultDisplayFormat and IModelRegisteredPropertyEditor.DefaultEditMask properties of a ViewItems | PropertyEditors | RegisteredPropertyEditor node.
Next Lesson: Use a Multiline Editor for String Properties