|
cfgridcolumn
DescriptionUsed
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.
Syntax<cfgridcolumn
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"
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.
HistoryColdFusion
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.
AttributesNote: 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
|
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.
|
bold
|
Optional;
all
|
As specified
by cfgrid
|
|
dataAlign
|
Optional;
applet, Flash
|
As specified
by cfgrid
|
Column data alignment:
|
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 cfgridcolHeaders attribute
is yes. The default value is yes.
|
headerAlign
|
Optional;
applet
|
As specified
by cfgrid
|
Column header text alignment:
|
headerBold
|
Optional;
HTML, applet
|
As specified
by cfgrid
|
|
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.
|
headerItalic
|
Optional;
HTML, applet
|
As specified
by cfgrid
|
|
headerTextColor
|
Optional;
HTML, applet
|
|
Color of grid control column header text.
|
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
|
|
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
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:
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.
|
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 cfgridselectmode 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
|
|
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:
|
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 attributeBy 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
= 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. 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
|
ExampleThe
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>
|