This chapter is from the book
This chapter is from the book
This chapter is from the book
Field Value Display Format
In addition to the FieldValueString property, the FieldTemplateUserControl class also provides another property called FieldValue, which returns the raw value object. At a cursory glance, the FieldValue property could be used to bind the Literal control as well. However, it is important to use the FieldValueString property as it automatically takes into account additional display format properties when converting the raw field value to a string:
- DataFormatString specifies a .NET format string that will be passed to the String.Format method to convert the field value to a display string.
- NullDisplayText specifies a replacement string that will be used when the raw field value is null.
- ConvertEmptyStringToNull is a Boolean value that determines whether an empty string value should treated as null and if the NullDisplayText will be used as a replacement for empty strings as well as null values. This property is true by default.
- HtmlEncode is a Boolean value that determines whether any special HTML symbols in the raw field value, such as '<' or '>', will be encoded using escape sequences, such as < and >. This property is true by default.
Display format properties can be specified in the data model by applying the DataTypeAttribute or the DisplayFormatAttribute to a particular column, as shown in Listing 3.3. The DisplayFormatAttribute, applied to the OrderDate column, specifies a long date {0:D} format string. The DataTypeAttribute, applied to the RequiredDate column, does not have its own DataFormatString property. Instead, it offers the DisplayFormat property, which gets a default DisplayFormatAttribute generated, based on the specified data type. For DataType.Date, the default data format string will be a short date {0:d}.
Listing 3.3. Specifying Display Format Using Data Annotations
using System.ComponentModel.DataAnnotations;
namespace DataModel
{
[MetadataType (typeof(Order.Metadata))]
partial class Order
{
public class Metadata
{
[DisplayFormat(DataFormatString = "{0:D}")]
public object OrderDate;
[DataType(DataType.Date)]
public object RequiredDate;
}
}
}
Display format properties can be also specified in page markup by setting the corresponding properties of the DynamicControl or DynamicField classes, similar to the properties of the “non-dynamic” BoundField. Listing 3.4 shows an example where a DynamicField is used in a GridView control and specifies a custom date format string {0:MM/dd/yy} for the ShippedDate column.
Listing 3.4. Specifying Data Format Using DynamicField
<%@ Page Language="C#"
MasterPageFile="~/Site.master" CodeBehind="SamplePage.aspx.cs"
Inherits="WebApplication.Samples.Ch01.DataFormatString.SamplePage" %>
<asp:Content ContentPlaceHolderID="ContentPlaceHolder1" runat="server">
<asp:GridView ID="gridView" runat="server" DataSourceID="dataSource"
AutoGenerateColumns="false" AllowPaging="true">
<columns>
<asp:DynamicField DataField="OrderDate" />
<asp:DynamicField DataField="RequiredDate" />
<asp:DynamicField DataField="ShippedDate" DataFormatString="{0:MM/dd/yy}" />
</columns>
</asp:GridView>
<asp:EntityDataSource ID="dataSource" runat="server"
ConnectionString="name=NorthwindEntities"
DefaultContainerName="NorthwindEntities" EntitySetName="Orders" />
</asp:Content>
Figure 3.1 shows the web page generated by this code. As you can see, the OrderDate values use the long format specified in the DisplayFormatAttribute in the model; the RequiredDate values use the short format provided by the DataTypeAttribute; and the ShippedDate values use the custom format specified in the page markup.
)
Figure 3.1. GridView with DataType and DisplayFormat attributes applied.
Inside of the field templates, the display format properties are available via the FormattingOptions property inherited from the FieldTemplateUserControl. The base class automatically initializes them based on the formatting options of the host—DynamicControl or DynamicField.
As you might expect, a fair amount of logic is involved in converting the raw field value to the final display string. By using the FieldValueString property of the FieldTemplateUserControl class, field templates ensure consistent behavior that offers application developers great flexibility in defining the presentation aspects of their data. The DataTypeAttribute allows specifying default display properties for a column in the data model based on its data type. The DisplayFormatAttribute allows fine-tuning it with the standard or custom format strings. Finally, the DynamicControl and DynamicField controls allow tailoring the display of column values for a specific page in a web application.