BoundField.DataFormatString Property
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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, setPublic Overridable Property DataFormatString As StringProperty Value
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.
