View comments | RSS feed

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.

Attributes

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.

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.

header

Optional;

All

yes

Column header text. Used only if the cfgrid colHeaders attribute is True (the default).

width

Optional;

All

Column head width

Column width, in pixels.

type

Optional;

All

 

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

yes
  • yes
  • no: hides the column.

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.

font

Optional;

All

As specified by cfgrid

Font of data in column.

fontSize

Optional;

All

As specified by cfgrid

Size of text in column.

italic

Optional;

All

As specified by cfgrid
  • yes: displays grid control text in italics.
  • no

bold

Optional;

All

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

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

as specified by cfgrid

Column header font.

headerFontSize

Optional;

Applet

as specified by cfgrid

Column header text size, in pixels.

headerItalic

Optional;

Applet

as specified by cfgrid
  • yes: displays column header in italics.
  • no

headerBold

Optional;

Applet

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

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.

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

, [comma]

Delimiter in values and valuesDisplay attributes.

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. (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 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:

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. 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>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


No screen name said on Feb 14, 2005 at 11:51 AM :
When using cfgrid format="flash" and SelectMode = "Edit", the
values = "Comma-separated strings and/or numeric range" does not create a drop-down combo-box within the grid to select from one of the given values. It is simply an edit box.
jrunrandy said on Feb 15, 2005 at 5:48 AM :
This is correct for flash forms, in the applet it will create a select list.
felixolow said on Feb 15, 2005 at 7:09 PM :
how do you select on a specific #Prj_Number# that is passed in? All I see are examples of SELECT * FROM COURSES?

i have tried #url.Prj_Number# with no success?

Thanks
Phil
jrunrandy said on Feb 17, 2005 at 7:31 AM :
felixolow:
The code example on this page doesn't use SELECT *. It names columns specifically.

You should, however, be able to use #url.Prj_Number# in a WHERE clause with no trouble. Look at http://livedocs.macromedia.com/coldfusion/7/htmldocs/00001261.htm for a simple example, although you should probably use cfqueryparam, as shown on http://livedocs.macromedia.com/coldfusion/7/htmldocs/00001257.htm.
brian_s said on Mar 7, 2005 at 11:17 AM :
It would be nice if there were an 'autowrap' feature for cfgridcolumn. If the string length is greater than the column width, then the column would wrap and 'stretch' the row until either all the text is displayed or a specified maximum cell height is reached.
lmjflash said on Apr 2, 2005 at 10:45 PM :
When using date/time formats in mask attribute, my output is incorrect. The ouput is whatever I put inthe mask attribute of cfgridcolumn. For example: <cfgridcolumn name="last_contact_dt" header="Last Contacted" display="yes" mask="yy/mm/dd"> will display yy/mm/dd in my grid (cfgrid type="flash"). If I remove the mask attribute then a long date format is displayed in my grid. Am I doing something wrong or is thius a bug?
No screen name said on Apr 5, 2005 at 8:18 AM :
I also have the exact same problem as mentioned by lmjflash when using the mask attribute and attempting to format a date/time field from the database.
soonersak said on Apr 7, 2005 at 8:13 PM :
I can't get the update to work when using Flash as the grid format. I have asked this question on the forum too, but no help.
kaigler said on Apr 19, 2005 at 12:31 PM :
when using mask wihtin a cfform type=flash, it does not allow for decimal places. if I enter something like: mask="9.999" it overlays the value in the grid with 0.000.

I ASSume the best way is to make sure the number is formatted correctly in the database and then there is no need for formatting? anyone else have this problem?
kaigler said on Apr 19, 2005 at 12:44 PM :
another quirky thing is if I have a field formatted as a number in my database ex: 0.000 and the value is say 30.000, when I pass it to the cfgridcolumn it losses all of the formatting that was passed. I understand why this happens but it would be nice to be able to maintain my preset formatting.

thanks
jrunrandy said on Apr 22, 2005 at 10:04 AM :
soonersak,
I asked a developer and this is what he said:
***
There is a known bug with the editable flash grid and html forms. I'm assuming this is how he is using it. He needs to either
a) use the flash grid in a flash form
b) use the applet grid in the html form.
***
No screen name said on Apr 22, 2005 at 1:53 PM :
*DATE MASKS MUST BE IN UPPER CASE*!

yy != YY

Cheers!
slowrey said on Apr 29, 2005 at 11:04 AM :
DATE MASK? Doesn't work for me. HELP? on this issue. I'm using mysql.
slowrey said on Apr 29, 2005 at 1:41 PM :
Field MUST BE TIMESTAMP FORMAT
Ad Bec said on May 28, 2005 at 2:17 PM :
Hi guys,

I realy need this valuesDisplay working for the flash format. Please submit this as the biggest request for the ColdFusion 7.1 issue
bdlemt said on Jun 3, 2005 at 6:19 PM :
The Mask did not work for me either; however, I just formated the datetime data in my query. I am using MYSQL; however, I am sure there is something similar for SQL server.

SELECT DATE_FORMAT(event_date, '%b %e %Y') as event_date
FROM somewhere

I guess they know about this bug?
icemanvko said on Jun 4, 2005 at 7:16 AM :
I had the problem with the mask in Access, and then I had the problem in MySql, I am wondering if I have the syntax wrong. I used the following

<cfgridcolumn name="MsgDate" mask="MM/DD/YY">

and my grid displayed MM/DD/YY in every row. On both Access, and SQL.

If I turn off the mask i get this in every row.

Fri Jun 3 00:00:00 GMT-0500 2005

The data in the database is from KIWI Syslog, and it seperates the date and time of the message into two fields, so the access field which is a Date/Time field, has a date in one field and a time in the other. Which is fine with me. but the grid mask is simply being ignored by the Flash Form. I tried changing the " to a ' and it did the same thing. I even went and installed MySQL, thinking it was some sort of Access issue, can someone who has this working tell me what I am doing wrong?
DaNewt said on Jun 14, 2005 at 9:18 AM :
I think the formatting is buggy.

The onlty workaround I can suggest that worked for me is to save the data into a text format. You can get the input using the dateField type. Then when you read it into a cfgrid, it will be formatted MM/DD/YY.
icemanvko said on Jun 14, 2005 at 9:27 AM :
Yes the Mask is definately BUGGED. I tried it with Access, and with MySQL, the Grid failed to mask the data in either case.

I found a work around using the following code:

SELECT
DATE_FORMAT(Msgdate, '%c/%e/%Y') AS MsgDate,
DATE_FORMAT(MsgTime, '%I:%i:%S:%p') AS MsgTime ,
MsgLevel ,
MsgHostname ,
MsgText
FROM syslogd

This is using MySQL database, so each database Vendor will have different format commands and syntax.
sloan2b said on Jun 22, 2005 at 9:56 AM :
to answer dbickel:
use type="currency" to get a currency value in the grid. If you bind it back to the field though you may need to strip "$" and "," if you have a masked input field.

to answer DaNewt:
seems to work fine if you use no mask and take the text (input.text) instead of the selected date (input.selectedDate) if the grid is empty. If the query that populates the grid returns records then use the mask="MM/DD/YYYY" on the gridcoulmn again taking the text and not selected date from the input. Just use a cfif and recordCount of the query in your code to determine if you need the mask or not. That will keep you from having to change the date in your SQL.
kmcdaniel said on Jun 24, 2005 at 9:47 AM :
Two things:

1. A type "password" should be added to the cfgridcolumn for format "Flash".

2. We need a way to be able to extend the update and/or delete functionality in cfgridupdate.

An alternative to #2 is to create #1 and then make it update only if the password was actually changed, and add an attribute that allows for CF hashing.

Thanks!
alon_aharoni said on Jul 6, 2005 at 12:53 AM :
how can i stop showing the ID colum in the cfgrid?

thanks
icemanvko said on Jul 6, 2005 at 7:09 AM :
add -> rowheaders="no"

to your cfgrid tag, and the numbers on the left side will go away if that is what you are asking.
Exspell said on Aug 21, 2005 at 8:03 PM :
Under cfgridcolumn syntax it states "textColor = "web color" or "expression"".

What happened to the documentation that existed in previous CF versions on using expressions with textcolor and bgcolor?
Jason Lim said on Oct 17, 2005 at 10:06 AM :
to answer samihoda2:
type="date" is definitely valid to me, without type="date" my cfgridupdate will throw an error.

I experience a problem with date mask with cfgridupdate
<cfgridcolumn mask="MMM DD YYYY"...
update without any problem with cfgridupdate
<cfgridcolumn mask="MMM DD YYYY EEE"...
throw an error saying date is not valid with cfgridupdate
Is that a bug? Aren't cfgridupdate will automatically convert it?

Thank you
uiswjd0 said on Jan 4, 2006 at 8:05 AM :
You MUST specify the type=date in order for the mask to take affect for date/time columns. if you don't you will get the output of what ever you type into the mask="MM/DD/YYYY"
GivinitLaldy said on Jun 28, 2006 at 2:23 PM :
I am extremely grateful to uiswjd0 for the type=date comment that solved the date mask problem in a flash cfgridcolumn - however is it my imagination, or is type=date NOT LISTED AS AN OPTION in the above documentation?

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000267.htm