Whatever message this page gives is out now! Go check it out!

cfgridcolumn

Last update:
May 18, 2026

Description

Used with the cfgrid tag in a cfform. Formats a column 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

autoExpand = "yes|no"

name = "column name"

bgColor = "web color|expression"

bold = "yes|no"

dataAlign = "left|right|center"

display = "yes|no"

font = "column font"

fontSize = "size"

header = "header"

headerAlign = "left|right|center"

headerBold = "yes|no"

headerFont = "font name"

headerFontSize = "size"

headerIcon = "icon path"

headerItalic = "yes|no"

headerMenu = "yes|no"

headerTextColor = "web color"

href = "URL"

hrefKey = "column name"

italic = "yes|no"

mask= "format mask"

numberFormat = "format"

select = "yes|no"

target = "URL target"

textColor = "web color|expression"

type = "type"

values = "comma-separated strings and/or numeric range"

valuesDelimiter = "delimiter character"

valuesDisplay = "comma-separated strings and/or numeric range"

width = "column width">
Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

cfgrid, cfgridrow, cfgridupdate, cfform, cfapplet, cfinput, cfselect, cfslider, cftextarea, cftree

History

ColdFusion 9.0.1: Added the attributes autoExpand and headerMenu supported only in HTML grids.
ColdFusion 9: Added boolean, date, numeric, and string_noCase to the type attribute values supported in HTML grids.
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.

Attributes

Note: In XML format, ColdFusion 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.
Attribute
Req/Opt; formats
Default
Description
autoExpand
Optional;HTML
yes for first column and no for remaining columns
On a particular column, it lets you expand

the specified column.

Setting autoExpand="yes" for multiple columns

results in error.

Also, if the attribute display is set to no, then autoExpand

cannot be yes; else, it results in error.
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.
bgColor
Optional;all
Color of background of grid column.
  • Options: same as for the textColor attribute.
bold
Optional;all
As specified by cfgrid
  • yes: displays grid control text in bold.
  • no
dataAlign
Optional;applet, Flash, HTML
As specified by cfgrid
Column data alignment:
  • left
  • right
  • center
display
Optional;all
yes
  • yes
  • no: hides the column.
font
Optional;all
As specified by cfgrid
Font of data in column.
fontSize
Optional;all
As specified by cfgrid
Size of text in column.
header
Optional;all
yes
Text for the column header.

Used only if the cfgrid colHeaders attribute is yes.

The default value is yes.
headerAlign
Optional;applet
As specified by cfgrid
Column header text alignment:
  • left
  • right
  • center
headerBold
Optional;HTML, applet
As specified by cfgrid
  • yes: displays header in bold.
  • no
headerFont
Optional;HTML, applet
As specified by cfgrid
Font for the column header.
headerFontSize
Optional;HTML, applet
As specified by cfgrid
Size of text for the column header, in pixels.
headerIcon
Optional
Location of an image file to use as the icon for

header column of the grid.
{{headerMenu}}Added in ColdFusion 9.0.1
Optional;HTML
no
Lets you turn on/off the header menu of the grid column.

Header menu is the drop-down list that appears on grid

header columns on mouse hover.

The attribute is helpful when you have images

for grid headers.
headerItalic
Optional;HTML, applet
As specified by cfgrid
  • yes: displays column header in italic.
  • no
headerTextColor
Optional;HTML, applet
Color of grid control column header text.
  • Options: same as for the textColor attribute.
href
Optional;HTML, applet
URL or query column name that contains a URL to

hyperlink each grid column with.
hrefKey
Optional;HTML, applet
The query column to use for the value appended to the href

URL of each column, instead of the column's value.
italic
Optional;all
As specified by cfgrid
  • yes: displays grid control text in italic.
  • no
mask
Optional;Flash, HTML
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 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 the section date/time formats in mask attribute.Masking supports HTML grids. The default format is m/d/y, for example 05/06/75. where m is month with leading zeros, d is day with leading zeros, and y is two-digit representation of year.
numberFormat
Optional;Applet
Format for displaying numeric data in the grid. See the following table of numberFormat attribute mask characters.
select
Optional;all
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.
target
Optional;HTML, Applet
Frame or standard HTML target in which to open link specified in href.
textColor
Optional;Applet, Flash, HTML
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. Limitations: In HTML format, must specify a valid HTML color. In Applet format, must be one of the following:
  • Any color, in hexadecimal format
  • Black
  • Red
  • Blue
  • Magenta
  • Cyan
  • Orange
  • Darkgray
  • Pink
  • Gray
  • White
  • Lightgray
  • Yellow
type
Optional;all
You can specify the following values in all formats:
  • boolean: column displays as check box; if cell is editable, user can change the check mark. In an onchange event, for static and dynamic grids, the data that is passed is converted to the format in which the boolean values are represented in the database.
  • combobox: displays a drop-down list with the values you specify for the attributes values and valuedisplay as options.
  • numeric: user can sort grid data numerically. In HTML format, if the cell is editable, the user can enter numeric values
  • string_noCase: user can sort grid data as case-insensitive text. In HTML format, if the cell is editable, the user can enter text values. You can specify the following value in applet and Flash formats; it does not work in HTML format:
  • 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 the image is larger than the column cell, it is clipped to fit. Flash images must be JPEG files. Applet images can be JPEG or GIF files. You can specify the following value in applet format; it does not work in Flash or HTML format.
  • 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 value in Flash format; it does not work in applet or HTML format:
  • currency: formats the column data as currency, aligning it around the decimal point. If users sort the grid by using this column, it sorts correctly for the currency, Use the mask attribute to specify a currency symbol; the default value is the dollar sign ($). You can specify the following value in HTML format; it does not work in applet or Flash format:
  • date: The column contains date values. If the grid selectMode attribute value is edit, the cell is editable. When you click an editable cell, an icon appears that you can click to open a date picker and select a date.
values
Optional;HTML, 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"}}
valuesDelimiter
Optional;HTML, applet
, (comma)
Delimiter in values and valuesDisplay attributes.
valuesDisplay
Optional;HTML, applet
Maps elements in the values attribute to string to display in the drop-down list. Delimited strings and/or numeric ranges.
width
Optional;all
Column head width
Column width, in pixels.
The following matrix describes the behavior of type="boolean".
Before
After
Y
N
T
F
1
0
true (for static grids)
false (for static grids)
true (for dynamic grids)
NO (for dynamic grids)
For non-boolean or null
Y
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. (The cfgridcolumn tag does not support international number formatting.)
Character
Meaning
_
(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 with 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:
Pattern letter
Description
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 = 03YYYY = 2003YYYYY = 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 = 7MM= 07MMM=JulMMMM= July
D
Day in month. Examples:D=4DD=04DD=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 = 1EE = 01EEE = MonEEEE = 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 = 3NN = 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. Avoid upper case 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>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page