CFGRIDCOLUMN |
Description Used with the cfgrid tag in a cfform. Formats a columns and optionally populates the column from a query. The font and alignment attributes used in cfgridcolumn override global font or alignment settings defined in cfgrid.
Category Forms tags
Syntax
    <cfgridcolumn
       name = "column_name"
       header = "header"
       width = "column_width"
       type = "type"
       display = "yes" or "no"
       select = "yes" or "no"
       font = "column_font"
       fontSize = "size"
       italic = "yes" or "no"
       bold = "yes" or "no"
       textColor = "web color" or "expression"
       bgColor = "web color" or "expression"
       dataAlign = "position"
    The following attribute applies to Flash format only
       mask= "format mask"
    The following attribute applies to applet format only
       href = "URL"
       hrefKey = "column_name"
       target = "URL_target"
       headerFont = "font_name"
       headerFontSize = "size"
       headerItalic = "yes" or "no"
       headerBold = "yes" or "no"
       headerTextColor = "web color"
       headerAlign = "position"
       numberFormat = "format"
       values = "Comma-separated strings and/or numeric range"
       valuesDisplay = "Comma-separated strings and/or numeric range"
       valuesDelimiter = "delimiter character">
See also cfgrid, cfgridrow, cfgridupdate, cfform, cfapplet, cfinput, cfselect, cfslider, cftextarea, cftree
History ColdFusion MX 7: Added the mask attribute, and the currency type attribute value. ColdFusion MX: Changed behavior if select="no": a user cannot select and edit the cell data, regardless of the cfgrid selectmode attribute value. When clicked, the cell border (and, depending on the selectColor value, the cell background) changes color, but the cell data cannot be edited.
Note: | In XML format, ColdFusion MX passes all attributes to the XML. The supplied XSLT skins do not handle or display XML format grids, but do display applet and Flash format grids.
numberFormat mask characters In applet format only, you can use the following numberFormat attribute mask characters to format output in U.S. numeric and currency styles. For more information on using these mask characters, see NumberFormat on page 1038. (The cfgridcolumn tag does not support international number formatting.)
_ | (Underscore) Digit placeholder.
9 | Digit placeholder.
. | (Period) Location of mandatory decimal point.
0 | Located to left or right of mandatory decimal point; pads with zeros.
( ) | Puts parentheses around mask if number is less than 0.
+ | Puts plus sign before positive numbers, minus sign before negative numbers.
- | Puts space before positive numbers, minus sign before negative numbers.
, | (Comma) Separates every third decimal-place with a comma.
L,C | Left-justify or center-justify number within width of mask column. First character of mask must be L or C. Default: right-justified.
$ | Puts dollar sign before formatted number. Must be the first character of mask.
^ | (Caret) Separates left from right formatting.
date/time formats in mask attribute By default, Flash displays date/time values in grid columns using a format that shows values such as Oct 29 2004 11:03:21. Use the mask attribute to display the date or time in a different format, as described in the following table:
Y | Year. If the number of pattern letters is two, the year is truncated to two digits; otherwise, it appears as four digits. The year can be zero-padded, as the third example shows in the following set of examples: Examples: YY = 03 YYYY = 2003 YYYYY = 02003
M | Month in year. The format depends on the following criteria: If the number of pattern letters is one, the format is interpreted as numeric in one or two digits. If the number of pattern letters is two, the format is interpreted as numeric in two digits. If the number of pattern letters is three, the format is interpreted as short text. If the number of pattern letters is four, the format is interpreted as full text. Examples: M = 7 MM= 07 MMM=Jul MMMM= July
D | Day in month. Examples: D=4 DD=04 DD=10
E | Day in week. The format depends on the following criteria: If the number of pattern letters is one, the format is interpreted as numeric in one or two digits. If the number of pattern letters is two, the format is interpreted as numeric in two digits. If the number of pattern letters is three, the format is interpreted as short text. If the number of pattern letters is four, the format is interpreted as full text. Examples: E = 1 EE = 01 EEE = Mon EEEE = Monday
A | AM/PM indicator.
J | Hour in day (0-23).
H | Hour in day (1-24).
K | Hour in am/pm (0-11).
L | Hour in am/pm (1-12).
N | Minute in hour. Examples: N = 3 NN = 03
S | Second in minute.
Other text | You can add other text into the pattern string to further format the string. You can use punctuation, numbers, and all lowercase letters. You should avoid uppercase letters because they may be interpreted as pattern letters. Example: EEEE, MMM. D, YYYY at H:NN A = Tuesday, Sept. 8, 2003 at 1:26 PM
Example The following example lets you update certain fields of the CourseList table in the cfdocexamples database. It uses cfgridcolumn tags to structure the table.
    <!--- If the gridEntered field exists, the form has been submitted.
          Update the database. --->
    <cfif IsDefined("form.gridEntered")>
       <cfgridupdate grid = "FirstGrid" dataSource = "cfdocexamples"
       tableName = "CourseList" keyOnly = "Yes">
    </cfif>

    <!--- Query the database to fill up the grid. --->
    <cfquery name = "GetCourses" dataSource = "cfdocexamples">
     SELECT Course_ID, Dept_ID, CorNumber,
         CorName, CorLevel, CorDesc
    FROM CourseList
    ORDER by Dept_ID ASC, CorNumber ASC
    </cfquery>

    <html>
    <head>
    <title>cfgrid Example</title>
    </head>
    <body>
    <h3>cfgrid Example</h3>
    <I>You can update the Name, Level, and Description information for courses.</i>
    <!--- The cfform tag must surround a cfgrid control. --->
    <cfform action = "#CGI.SCRIPT_NAME#">
       <cfgrid name = "FirstGrid" width = "500"
             query = "GetCourses" colheaderbold="Yes"
             font = "Tahoma" rowHeaders = "No"
             selectColor = "Red" selectMode = "Edit" >
          <!--- cfgridcolumn tags arrange the table and control the display. --->
          <!--- Hide the primary key, required for update --->
          <cfgridcolumn name = "Course_ID" display = "No">
          <!--- select="No" does not seem to have any effect !!! --->
          <cfgridcolumn name = "Dept_ID" header = "Department" Select="No"
             width="75" textcolor="blue" bold="Yes">
          <cfgridcolumn name = "CorNumber" header = "Course ##" Select="No"
             width="65">
          <cfgridcolumn name = "CorName" header = "Name" width="125">
          <cfgridcolumn name = "CorLevel" header = "Level" width="85">
          <cfgridcolumn name = "CorDesc" header = "Description" width="125">
       </cfgrid>
       <br>
       <cfinput type="submit" name="gridEntered">
    </cfform>
    </body>
    </html>

NAME |
| Required;
| All
Name of the grid column element. If the grid uses a query, this attribute must be the name of the query column that populates the grid column.

HEADER |
| Optional;
| All
Default value: "yes" Column header text. Used only if the cfgrid colHeaders attribute is True (the default).

WIDTH |
| Optional;
| All
Default value: "Column head width" Column width, in pixels.

TYPE |
| Optional;
| All
Default value: " " You can specify the following values in all formats: image: grid displays the image specified by the URL in the column. If you use a relative URL, the image must be in the CFIDE\classes directory or a subdirectory. If image is larger than column cell, it is clipped to fit. Flash images must be JPEG files. Applet images can be JPEG or GIF files. boolean: column displays as check box; if cell is editable, user can change the check mark. numeric: user can sort grid data numerically. string_noCase: user can sort grid data as case-insensitive text. You can specify the following attribute in applet format; it does not work in Flash grids. image: you can use the following built-in ColdFusion image names, in addition to paths to image files, in the column values: - cd - computer - document - element - folder - floppy - fixed - remote You can specify the following attribute in Flash format; it does not work in applet grids: currency: formats the column data as currency, aligning it around the decimal point. If users sort the grid using this column, it will sort correctly for the currency, Use the mask attribute to specify a currency symbol, which defaults to the dollar sign ($).

DISPLAY |
| Optional;
| All
Default value: "yes" yes no: hides the column.

SELECT |
| Optional;
| All
Default value: "yes" Determines selection behavior if the cfgrid selectmode attribute value is column, edit, or single; ignored for row or browse values. yes: users can select the column or select or edit cells in the column, as specified by the selectmode attribute. no: users cannot select the column or select or edit cells in the column.

FONT |
| Optional;
| All
Default value: "As specified by cfgrid" Font of data in column.

FONTSIZE |
| Optional;
| All
Default value: "As specified by cfgrid" Size of text in column.

ITALIC |
| Optional;
| All
Default value: "As specified by cfgrid" yes: displays grid control text in italics. no

BOLD |
| Optional;
| All
Default value: "As specified by cfgrid" yes: displays grid control text in bold. no

TEXTCOLOR |
| Optional;
| All
Color of grid element text in column as a hexadecimal number or text name. To enter a hexadecimal value, use the form "##xxxxxx", where x = 0-9 or A-F; use two number signs or none. Any color, in hexadecimal format Black Red Blue Magenta Cyan Orange Darkgray Pink Gray White Lightgray Yellow

BGCOLOR |
| Optional;
| All
Color of background of grid column. Options: same as for the textColor attribute.

DATAALIGN |
| Optional;
| All
Default value: "as specified by cfgrid" Column data alignment: Left Right Center

mask

optional;Flash

A mask pattern that controls the character pattern that the form displays or allows users to input and sends to ColdFusion.

For columns with the currency type attribute, the mask specifies the currency symbol. ColdFusion MX automatically inserts the character before the numeric value.

For columns with text or numeric values, mask specifies the format to display or allow users to input, as follows:

- A = [A-Za-z]
- X = [A-Za-z0-9]
- 9 = [0-9]
- ? = Any character
- All other characters = ColdFusion inserts the literal character.

If the column values are dates or timestamps, ColdFusion uses the mask pattern to format the selected date.

For details of the date/time mask format, see date/time formats in mask attribute.

HREF |
| Optional;
| Applet
URL or query column name that contains a URL to hyperlink each grid column with.

HREFKEY |
| Optional;
| Applet
The query column to use for the value appended to the href URL of each column, instead of the column's value.

TARGET |
| Optional;
| Applet
Frame in which to open link specified in href.

HEADERFONT |
| Optional;
| Applet
Default value: "as specified by cfgrid" Column header font.

HEADERFONTSIZE |
| Optional;
| Applet
Default value: "as specified by cfgrid" Column header text size, in pixels.

HEADERITALIC |
| Optional;
| Applet
Default value: "as specified by cfgrid" yes: displays column header in italics. no

HEADERBOLD |
| Optional;
| Applet
Default value: "as specified by cfgrid" yes: displays header in bold. no

HEADERTEXTCOLOR |
| Optional;
| Applet
Color of grid control column header text. Options: same as for the textColor attribute.

HEADERALIGN |
| Optional;
| Applet
Default value: "as specified by cfgrid" Column header text alignment: Left Right Center

NUMBERFORMAT |
| Optional;
| Applet
Format for displaying numeric data in the grid. See "numberFormat mask characters" on page 453.

VALUES |
| Optional;
| Applet
Formats cells in column as drop-down list boxes; specify items in drop-down list. For example:
    values = "arthur, scott, charles, 1-20, mabel"

VALUESDISPLAY |
| Optional;
| Applet
Maps elements in the values attribute to string to display in the drop-down list. Delimited strings and/or numeric range(s).

VALUESDELIMITER |
| Optional;
| Applet
Default value: ", [comma]" Delimiter in values and valuesDisplay attributes.