cfgridcolumn

Description

Used with cfgrid in a cfform, you use cfgridcolumn to specify column data in a cfgrid control. Font and alignment attributes used in cfgridcolumn override any global font or alignment settings defined in cfgrid.

Syntax


<cfgridcolumn name = "column_name"

  header = "header"

  width = "column_width"

  font = "column_font"

  fontSize = "size"

  italic = "Yes" or "No"

  bold = "Yes" or "No"

  textColor = "Web color" or "expression"

  bgColor = "Web color" or "expression"

  href = "URL"

  hrefKey = "column_name"

  target = "URL_target"

  select = "Yes" or "No"

  display = "Yes" or "No"

  type = "type"

  headerFont = "font_name"

  headerFontSize = "size"

  headerItalic = "Yes" or "No"

  headerBold = "Yes" or "No"

  colHeaderTextColor = "Web color"

  dataAlign = "position"

  headerAlign = "position"

  numberFormat = "format"

  values = "Comma separated strings and/or numeric range"

  valuesDisplay = "Comma separated strings and/or numeric range"

  valuesDelimiter = "delimiter character">

Attributes

Attribute

Description

name
Required. A name for the grid column element. If the grid uses a query, the column name must specify the name of a query column.

header
Optional. Text for the column header. The value of header is used only when the cfgrid colHeaders attribute is Yes (or omitted, since it defaults to Yes).

width
Optional. The width of the column, in pixels. Default is the width of the column head text.

font
Optional. Font name to use for data in the column. Defaults is the font specified by cfgrid.

fontSize
Optional. Font size for text in the column. Default is the font specified by cfgrid.

italic
Optional. Yes or No. Yes displays all grid control text in italic. Default is as specified by the corresponding attribute of cfgrid.

bold
Optional. Yes or No. Yes displays all grid control text in boldface. Default is as specified by the corresponding attribute of cfgrid.

textColor
Optional. Color value for grid element text in the grid column, or an expression you can use to manipulate text color in grid column elements.
Valid color entries are: black (default), magenta, cyan, orange, darkgray, pink, gray, white, lightgray, yellow. A hex value can be entered in the form:
textColor = "##xxxxxx"
Where x is 0-9 or A-F. Use either two pound signs or no pound signs.
You can enter an expression in the place of a specific color value. For example:
textColor = "(C2 LT 0 ? red : black)"
This example reads as follows: 'If the current value in Column 2 is Less Than 0 (zero), show the value as red text. If the current value in Column 2 is greater than 0, show the value as black text.'
For information on expression operators, see "Using expressions in textColor and bgColor attributes".

bgColor
Optional. Color value for the background of the grid column, or an expression you can use to manipulate grid column background color.
Valid color entries are: black, magenta, cyan, orange, darkgray, pink, gray, white (default), lightgray, yellow. A hex value can be entered in the form:
bgColor = "##xxxxxx"
Where x is 0-9 or A-F. Use either two pound signs or no pound signs.
You can enter an expression in place of a color value. For example:
bgColor = "(CX LT 0 ? lightgray : yellow)"
This example reads as follows: 'if the current value in Column 2 is Less Than 0 (zero), show the value as red text. If the current value in Column 2 is greater than 0, show the value as black text.'
For information on expression operators, see "Using expressions in textColor and bgColor attributes".

href
Optional. URL to associate with the grid item. You can specify a URL that is relative to the current page:
../mypage.cfm
Or an absolute URL:
http://myserver.com/mydir/mypage.cfm

hrefKey
Optional. The name of a query column when the grid uses a query. The column specified becomes the Key regardless of the select mode for the grid.

target
Optional. The name of the frame in which to open the link specified in href.

select
Optional. Yes or No. Yes lets end users select a column in a grid control. When No, the column cannot be edited, even if the cfgrid insert or delete attributes are enabled. The value of the select attribute is ignored if the cfgrid selectMode attribute is set to Row or Browse.

display
Optional. Yes or No. Use to hide columns. Default is Yes to display the column.

type
Optional. Enter image, numeric, boolean, or string_noCase.
When type = "image", the grid attempts to display an image corresponding to the value in the column, which can be a built-in ColdFusion image name, or an image in the cfide\classes directory or a subdirectory, referenced with a relative URL. Built-in image names are as follows:

cd

computer

document

element

folder

floppy

fixed

remote

If an image is larger than the column cell in which it is placed, the images is clipped to fit.
If type = "numeric", data in the grid can be sorted by the end user as numeric data rather than as simple character text.
If type = "boolean", the column displays as a checkbox, and if the cell is editable, the user can change the checkmark setting.
If type = "string_noCase", data in the grid can be sorted by the end user as case insensitive text data, like an Excel spreadsheet, rather than as case sensitive character text.

headerFont
Optional. Font to use for the column header. Default is as specified by the corresponding attribute of cfgrid.

headerFontSize
Optional. Font size to use for the column header, in pixels. Default is as specified by the corresponding attribute of cfgrid.

headerItalic
Optional. Yes or No. Yes displays column header text in italic. Default is as specified by the corresponding attribute of cfgrid.

headerBold
Optional. Yes or No. Yes displays header text in boldface. Default is as specified by the corresponding attribute of cfgrid.

colHeaderTextColor
Optional. Color value for the grid control column header text. Entries are: black (default), magenta, cyan, orange, darkgray, pink, gray, white, lightgray, yellow.
A hex value can be entered in the form:
colHeaderTextColor = "##xxxxxx"
where x is 0-9 or A-F. Use either two pound signs or no pound signs.

dataAlign
Optional. Alignment for column data. Entries are: left, center, or right. Default is as specified by cfgrid.

headerAlign
Optional. Alignment for the column header text. Default is as specified by cfgrid. Valid entries are:

left

center

right

numberFormat
Optional. The format for displaying numeric data in the grid. For information about mask characters, see "numberFormat mask characters".

values
Optional. Formats cells in the column as drop down list boxes. lets end users select an item in a drop down list. Use the values attribute to specify the items you want to appear in the drop down list.
values = "arthur, scott, charles, mabel"
You can specify a range of numbers:
values = "1-10"
You can mix numeric ranges and string values:
values = "arthur, scott, charles, 1-20, mabel"

valuesDisplay
Optional. Used to map elements specified in the values attribute to a string of your choice to display in the drop down list. Enter comma separated strings and/or numeric range(s).

valuesDelimiter
Optional. Character to use as a delimiter in the values and valuesDisplay attributes. Default is "," (comma).

Attribute	Description
name	Required. A name for the grid column element. If the grid uses a query, the column name must specify the name of a query column.
header	Optional. Text for the column header. The value of `header` is used only when the `cfgrid` `colHeaders` attribute is Yes (or omitted, since it defaults to Yes).
width	Optional. The width of the column, in pixels. Default is the width of the column head text.
font	Optional. Font name to use for data in the column. Defaults is the font specified by `cfgrid`.
fontSize	Optional. Font size for text in the column. Default is the font specified by `cfgrid`.
italic	Optional. Yes or No. Yes displays all grid control text in italic. Default is as specified by the corresponding attribute of `cfgrid`.
bold	Optional. Yes or No. Yes displays all grid control text in boldface. Default is as specified by the corresponding attribute of `cfgrid`.
textColor	Optional. Color value for grid element text in the grid column, or an expression you can use to manipulate text color in grid column elements. Valid color entries are: black (default), magenta, cyan, orange, darkgray, pink, gray, white, lightgray, yellow. A hex value can be entered in the form: textColor = "##xxxxxx" Where x is 0-9 or A-F. Use either two pound signs or no pound signs. You can enter an expression in the place of a specific color value. For example: textColor = "(C2 LT 0 ? red : black)" This example reads as follows: 'If the current value in Column 2 is Less Than 0 (zero), show the value as red text. If the current value in Column 2 is greater than 0, show the value as black text.' For information on expression operators, see "Using expressions in textColor and bgColor attributes".
bgColor	Optional. Color value for the background of the grid column, or an expression you can use to manipulate grid column background color. Valid color entries are: black, magenta, cyan, orange, darkgray, pink, gray, white (default), lightgray, yellow. A hex value can be entered in the form: bgColor = "##xxxxxx" Where x is 0-9 or A-F. Use either two pound signs or no pound signs. You can enter an expression in place of a color value. For example: bgColor = "(CX LT 0 ? lightgray : yellow)" This example reads as follows: 'if the current value in Column 2 is Less Than 0 (zero), show the value as red text. If the current value in Column 2 is greater than 0, show the value as black text.' For information on expression operators, see "Using expressions in textColor and bgColor attributes".
href	Optional. URL to associate with the grid item. You can specify a URL that is relative to the current page: ../mypage.cfm Or an absolute URL: http://myserver.com/mydir/mypage.cfm
hrefKey	Optional. The name of a query column when the grid uses a query. The column specified becomes the Key regardless of the select mode for the grid.
target	Optional. The name of the frame in which to open the link specified in `href`.
select	Optional. Yes or No. Yes lets end users select a column in a grid control. When No, the column cannot be edited, even if the `cfgrid` `insert` or `delete` attributes are enabled. The value of the `select` attribute is ignored if the `cfgrid` `selectMode` attribute is set to Row or Browse.
display	Optional. Yes or No. Use to hide columns. Default is Yes to display the column.
type	Optional. Enter `image`, `numeric`, `boolean`, or `string_noCase`. When `type = "image"`, the grid attempts to display an image corresponding to the value in the column, which can be a built-in ColdFusion image name, or an image in the `cfide\classes` directory or a subdirectory, referenced with a relative URL. Built-in image names are as follows: cd computer document element folder floppy fixed remote If an image is larger than the column cell in which it is placed, the images is clipped to fit. If `type = "numeric"`, data in the grid can be sorted by the end user as numeric data rather than as simple character text. If `type = "boolean"`, the column displays as a checkbox, and if the cell is editable, the user can change the checkmark setting. If `type = "string_noCase"`, data in the grid can be sorted by the end user as case insensitive text data, like an Excel spreadsheet, rather than as case sensitive character text.
headerFont	Optional. Font to use for the column header. Default is as specified by the corresponding attribute of `cfgrid`.
headerFontSize	Optional. Font size to use for the column header, in pixels. Default is as specified by the corresponding attribute of `cfgrid`.
headerItalic	Optional. Yes or No. Yes displays column header text in italic. Default is as specified by the corresponding attribute of `cfgrid`.
headerBold	Optional. Yes or No. Yes displays header text in boldface. Default is as specified by the corresponding attribute of `cfgrid`.
colHeaderTextColor	Optional. Color value for the grid control column header text. Entries are: black (default), magenta, cyan, orange, darkgray, pink, gray, white, lightgray, yellow. A hex value can be entered in the form: colHeaderTextColor = "##xxxxxx" where x is 0-9 or A-F. Use either two pound signs or no pound signs.
dataAlign	Optional. Alignment for column data. Entries are: `left`, `center`, or `right`. Default is as specified by `cfgrid`.
headerAlign	Optional. Alignment for the column header text. Default is as specified by `cfgrid`. Valid entries are: `left` `center` `right`
numberFormat	Optional. The format for displaying numeric data in the grid. For information about mask characters, see "numberFormat mask characters".
values	Optional. Formats cells in the column as drop down list boxes. lets end users select an item in a drop down list. Use the `values` attribute to specify the items you want to appear in the drop down list. values = "arthur, scott, charles, mabel" You can specify a range of numbers: values = "1-10" You can mix numeric ranges and string values: values = "arthur, scott, charles, 1-20, mabel"
valuesDisplay	Optional. Used to map elements specified in the `values` attribute to a string of your choice to display in the drop down list. Enter comma separated strings and/or numeric range(s).
valuesDelimiter	Optional. Character to use as a delimiter in the `values` and `valuesDisplay` attributes. Default is "," (comma).

Using expressions in textColor and bgColor attributes

The textColor and bgColor attributes accept a color value literal or an expression that lets you select a text color based on the evaluation of a simple boolean expression. The basic syntax for this expression is as follows:

(CX operator string ? true_condition : false_condition)

Where:

CX The column containing the value you want to test. Use CX for the current column and Cn, where n is the column you want to evaluate; for example, C2
operator One of the following ColdFusion operators: EQ (equal), GT (greater than), LT (less than)
string String representing the value to compare against. This can be a literal string, as in (C2 EQ Johnson ? blue : green), or a numeric value: (C2 LT 0 ? red : black)
true_condition value for textColor if condition evaluates to "true"
false_condition value for textColor if condition evaluates to "false"

The comparisons in the expression are interpreted as numeric if the string supplied in the expression can be interpreted as a number. Otherwise the comparison is a standard string comparison.

Example

This code fragment shows an expression that changes the text color for the grid element to blue if the grid element contains the string "Peter," and black otherwise.

<cfgridcolumn name = "FirstName" textColor = "(CX EQ Peter ?

  blue : black)">

The next example displays the text in red if the value in column 1 is greater than four and black otherwise:

<cfgridcolumn name = "FirstName" textColor = "(C1 GT 4 ? blue : black)">

numberFormat mask characters

Mask characters you can use in the numberFormat attribute correspond to those used in the NumberFormat CFML function. For more information, see Chapter 3, "ColdFusion Functions".

Character

Meaning

_ (underscore)
Optional digit placeholder.

9
Optional digit placeholder. Same as _ but shows decimal places more clearly.

.
Specifies the location of a mandatory decimal point.

0
Located to the left or right of a mandatory decimal point, to force padding with zeros.

( )
Places parentheses around the mask if the number is less than 0.

+
Places + in front of positive numbers, - in front of negative numbers.

-
Place " " (space) in front of positive numbers, - in front of negative numbers.

,
Separates thousands with commas.

L,C
Specifies left-justify or center-justify a number within the width of the mask column. L or C must appear as the first character of the mask. By default, numbers are right-justified.

$
Places a dollar sign in front of a formatted number. $ must appear as the first character of the mask.

^
Separates left from right formatting.

Character	Meaning
_ (underscore)	Optional digit placeholder.
9	Optional digit placeholder. Same as _ but shows decimal places more clearly.
.	Specifies the location of a mandatory decimal point.
0	Located to the left or right of a mandatory decimal point, to force padding with zeros.
( )	Places parentheses around the mask if the number is less than 0.
+	Places + in front of positive numbers, - in front of negative numbers.
-	Place " " (space) in front of positive numbers, - in front of negative numbers.
,	Separates thousands with commas.
L,C	Specifies left-justify or center-justify a number within the width of the mask column. L or C must appear as the first character of the mask. By default, numbers are right-justified.
$	Places a dollar sign in front of a formatted number. $ must appear as the first character of the mask.
^	Separates left from right formatting.

Example

<!--- This example shows the cfgridcolumn tag in action --->

...

<cfgrid name = "FirstGrid" width = "450" 

  query = "GetCourses" insert = "Yes"

  delete = "Yes" sort = "Yes" 

  font = "Tahoma" bold = "No" italic = "No"

  appendKey = "No" highlightHref = "No" 

  gridDataAlign = "LEFT"

  gridLines = "Yes" rowHeaders = "Yes" 

  rowHeaderAlign = "LEFT" rowHeaderItalic = "No"

  rowHeaderBold = "No" colHeaders = "Yes" 

  colHeaderAlign = "LEFT" colHeaderItalic = "No" 

  colHeaderBold = "No" selectColor = "Red"

  selectMode = "EDIT" pictureBar = "No" 

  insertButton = "To insert" deleteButton = "To delete" 

  sortAscendingButton = "Sort ASC" 

    sortDescendingButton = "Sort DESC">

  <cfgridcolumn name = "Course_ID" dataAlign = "LEFT" 

    bold = "No" italic = "No"

    select = "No" display = "No" 

    headerBold = "No" headerItalic = "No">

  <cfgridcolumn name = "Dept_ID" header = "Department"

    headerAlign = "LEFT" dataAlign = "LEFT" bold = "Yes" 

      italic = "No"

    select = "Yes" display = "Yes" headerBold = "No" 

      headerItalic = "Yes">

  <cfgridcolumn name = "CorNumber" header = "Course ##"

    headerAlign = "LEFT" dataAlign = "LEFT" 

    bold = "No" italic = "No"

    select = "Yes" display = "Yes" 

    headerBold = "No" headerItalic = "No">

  <cfgridcolumn name = "CorName" header = "Name" 

    headerAlign = "LEFT" dataAlign = "LEFT" 

    font = "Times" bold = "No" 

    italic = "No" select = "Yes"

    display = "Yes" headerBold = "No" 

    headerItalic = "No">

  <cfgridcolumn name = "CorLevel" header = "Level" 

    headerAlign = "LEFT" dataAlign = "LEFT" 

    bold = "No" italic = "No" select = "Yes" 

    display = "Yes" headerBold = "No" 

    headerItalic = "No">

    ...

cfgridcolumn

Description

Category

Syntax

See also

Attributes

Using expressions in textColor and bgColor attributes

Example

numberFormat mask characters

Example

CFML Reference
ColdFusion Tags