Edit

BoundField.DataFormatString Property

  • Reference

Definition

Namespace:
System.Web.UI.WebControls
Assembly:
System.Web.dll

Gets or sets the string that specifies the display format for the value of the field.

public:
 virtual property System::String ^ DataFormatString { System::String ^ get(); void set(System::String ^ value); };
public virtual string DataFormatString { get; set; }
member this.DataFormatString : string with get, set
Public Overridable Property DataFormatString As String

Property Value

String

A formatting string that specifies the display format for the value of the field. The default is an empty string (""), which indicates that no special formatting is applied to the field value.

Examples

A Visual Studio Web site project with source code is available to accompany this topic: Download.

The following example shows how to use the DataFormatString property to specify a custom display format for the values of a field.

The following example shows one row of the output that is produced by this example.

ProductID Name ProductNumber ListPrice Weight ModifiedDate
000680 HL Road Frame - Black, 58 #FR-R92B-58 $1,431.50 1016.040 3/11/2004

Remarks

Use the DataFormatString property to specify a custom display format for the values that are displayed in the BoundField object. If the DataFormatString property is not set, the field's value is displayed without any special formatting.

Note

In versions of ASP.NET earlier than 3.5, you must set the HtmlEncode property to false in order to format fields that are not string data types. Otherwise, the field value is converted to a string by the default conversion method before the format string that is stored in the DataFormatString property is applied.

By default, the formatting string is applied to the field value only when the data-bound control that contains the BoundField object is in read-only mode. To apply the formatting string to field values while in edit mode, set the ApplyFormatInEditMode property to true.

The formatting string can be any literal string and usually includes a placeholder for the field's value. For example, in the formatting string Item Value: {0}, the field's value is substituted for the {0} placeholder when the string is displayed in the BoundField object. The rest of the formatting string is displayed as literal text.

If the formatting string does not include a placeholder, only the formatting string itself is included in the final display text (the field's value from the data source is not included). If the placeholder is a 0 (zero) enclosed in curly braces as shown in the preceding example, the field value is converted to a string by the default method. You can append to the zero a string that specifies how the field value should be formatted. For example, the placeholder {0:C} for a numeric field specifies that value of the field should be converted to a currency format.

Formatting is applied by using the Format method. The number that follows the left curly brace is part of the syntax used by that method and indicates which one of a series of values the placeholder should use. Because there is only one field value in each cell, the number that follows the left curly brace can only be set to 0.

The following table lists the standard format characters for numeric fields. These format characters are not case-sensitive, except for X, which displays hexadecimal characters in the case that is specified. You can append a number to most format characters in order to specify how many significant digits or decimal places you want to display.

Note

In most cases, formatting depends on the server's culture setting. The examples are for a culture setting of en-US.

Format character Description Example
C or c Displays numeric values in currency format. You can specify the number of decimal places. Format: {0:C}

123.456 -> $123.46

Format: {0:C3}

123.456 -> $123.456
D or d Displays integer values in decimal format. You can specify the number of digits. (Although the type is referred to as "decimal", the numbers are formatted as integers.) Format: {0:D}

1234 -> 1234

Format: {0:D6}

1234 -> 001234
E or e Displays numeric values in scientific (exponential) format. You can specify the number of decimal places. Format: {0:E}

1052.0329112756 -> 1.052033E+003

Format: {0:E2}

-1052.0329112756 -> -1.05e+003
F or f Displays numeric values in fixed format. You can specify the number of decimal places. Format: {0:F}

1234.567 -> 1234.57

Format: {0:F3}

1234.567 -> 1234.567
G or g Displays numeric values in general format (the most compact of either fixed-point or scientific notation). You can specify the number of significant digits. Format: {0:G}

-123.456 -> -123.456

Format: {0:G2}

-123.456 -> -120
N or n Displays numeric values in number format (including group separators and optional negative sign). You can specify the number of decimal places. Format: {0:N}

1234.567 -> 1,234.57

Format: {0:N4}

1234.567 -> 1,234.5670
P or p Displays numeric values in percent format. You can specify the number of decimal places. Format: {0:P}

1 -> 100.00%

Format: {0:P1}

.5 -> 50.0%
R or r Displays Single, Double, or BigInteger values in round-trip format. Format: {0:R}

123456789.12345678 -> 123456789.12345678
X or x Displays integer values in hexadecimal format. You can specify the number of digits. Format: {0:X}

255 -> FF

Format: {0:x4}

255 -> 00ff

For more information and for examples that show formatting for other culture values, see Standard Numeric Format Strings. You can also create custom numeric format strings. For more information, see Custom Numeric Format Strings.

The following table lists format characters for DateTime fields. Most of these formatting specifications result in a different output depending on culture settings. The examples are for a DateTime value of 6/15/2009 1:45:30 PM with a culture setting of en-US.

Format character Description Example
d Short date pattern. Format: {0:d}

6/15/2009 1:45:30 PM -> 6/15/2009
D Long date pattern. Format: {0:D}

6/15/2009 1:45:30 PM ->Monday, June 15, 2009
f Full date/time pattern (short time). Format: {0:f}

6/15/2009 1:45:30 PM -> Monday, June 15, 2009 1:45 PM
F Full date/time pattern (long time). Format: {0:F}

6/15/2009 1:45:30 PM -> Monday, June 15, 2009 1:45:30 PM
g General date/time pattern (short time). Format: {0:g}

6/15/2009 1:45:30 PM -> 6/15/2009 1:45 PM
G General date/time pattern (long time). Format: {0:G}

6/15/2009 1:45:30 PM -> 6/15/2009 1:45:30 PM
M or m Month/day pattern. Format: {0:M}

6/15/2009 1:45:30 PM -> June 15
O or o Round-trip date/time pattern. Format: {0:o}

6/15/2009 1:45:30 PM -> 2009-06-15T13:45:30.0900000
R or r RFC1123 pattern (for information, see DateTimeFormatInfo.RFC1123Pattern). Format: {0:R}

6/15/2009 1:45:30 PM -> Mon, 15 Jun 2009 20:45:30 GMT
s Sortable date/time pattern. Format: {0:s}

6/15/2009 1:45:30 PM -> 2009-06-15T13:45:30
t Short time pattern. Format: {0:t}

6/15/2009 1:45:30 PM -> 1:45 PM
T Long time pattern. Format: {0:T}

6/15/2009 1:45:30 PM -> 1:45:30 PM
u Universal sortable date/time pattern. Format: {0:u}

6/15/2009 1:45:30 PM -> 2009-06-15 20:45:30Z
U Universal full date/time pattern. Format: {0:U}

6/15/2009 1:45:30 PM -> Monday, June 15, 2009 8:45:30 PM
Y or y Year month pattern. Format: {0:Y}

6/15/2009 1:45:30 PM -> June, 2009

For more information and for examples that show formatting for other culture values, see Standard Date and Time Format Strings. You can also create custom date and time format strings. For more information, see Custom Date and Time Format Strings.

Applies to

See also