cfgrid

Used within the cfform tag. Puts a grid control (a table of
data) in a CFML form. To specify grid columns and row
data, use the cfgridcolumn and cfgridrow tags, or use the
query attribute, with or without cfgridcolumn tags.

  <cfgrid name="">

 cfgrid(name="");

This tag requires Adobe ColdFusion 3 and up.  Not supported on Lucee, etc.

Discouraged: The use of tags generating UI is generally discouraged by the CFML community. See: https://static.raymondcamden.com/cfuitherightway/cfgrid/index.html

  1. CFDocs
  2. Tags
  3. UI Tags
  4. cfgrid
  5. CF3+
  6. 0 Issue
  7. Edit
See Also:   cfgridcolumn   cfgridrow   cfgridupdate

Attribute Reference

name string
Required

Name of grid element.

bind string

A bind expression specifying used to fill the
contents of the grid. Cannot be used with the
query attribute.

pagesize numeric

The number of rows to display per page for a
dynamic grid. If the number of available rows
exceeds the page size, the grid displays only
the specified number of entries on a single
page, and the user navigates between pages
to show all data. The grid retrieves data for
each page only when it is required for display.
This attribute is ignored if you specify a query
attribute.

striperowcolor string

The color to use for one of the alternating
stripes. The bgColor setting determines the
other color

preservepageonsort boolean
Default: true

Specifies whether to display the page with
the current page number, or display page 1,
after sorting (or resorting) the grid

striperows boolean
Default: true

Specifies whether to display the page with
the current page number, or display page 1,
after sorting (or resorting) the grid

format string
Default: applet

- applet: generates a Java applet.
- Flash: generates a Flash grid control.
- xml: generates an XMLrepresentation of the grid.
In XML format forms, includes the generated XML in the form.
In HTML format forms, puts the XML in a string variable
with the name specified by the name attribute.
Default: applet
Values:
  • applet
  • flash
  • xml
  • html

height numeric
Default: 300

Control's height, in pixels.
Default for applet: 300

width numeric

Control's width, in pixels.
Default for applet: 300

autowidth boolean
Default: false

Yes: sets column widths so that all columns display within
grid width.
No: sets columns to equal widths. User can resize columns.
Horizontal scroll bars are not available, because if
you specify a column width and set autoWidth = "Yes",
CFML sets to this width, if possible

vspace numeric

Vertical margin above and below control, in pixels.

hspace numeric

Horizontal spacing to left and right of control, in pixels.

align string

Alignment of the grid cell contents
Values:
  • top
  • left
  • bottom
  • baseline
  • texttop
  • absbottom
  • middle
  • absmiddle
  • right

query query

Name of query associated with grid control.

insert boolean
Default: false

User can insert row data in grid.
Takes effect only if selectmode="edit"

delete boolean
Default: false

User can delete row data from grid.
Takes effect only if selectmode="edit"

sort boolean
Default: false

The sort button performs simple text sort on column. User
can sort columns by clicking column head or by clicking
sort buttons. Not valid with selectmode=browse.

Yes: sort buttons display on grid control

font string
Default: arial

Font of data in column.
Values:
  • arial
  • times
  • courier
  • arialunicodeMS

fontsize numeric

Size of text in column.

italic boolean
Default: false

Yes: displays grid control text in italics

bold boolean
Default: false

Yes: displays grid control text in bold

textcolor string
Default: black

Text color for control. For a hex value, use the form:
textColor = "##xxxxxx", where x = 0-9 or A-F; use two hash
signs or none.
Values:
  • black
  • red
  • blue
  • magenta
  • cyan
  • orange
  • darkgray
  • pink
  • white
  • lightgray
  • yellow

href string

URL or query column name that contains a URL to hyperlink
each grid column with.

hrefkey string

The query column to use for the value appended to the href
URL of each column, instead of the column's value.

target string

Frame in which to open link specified in href.

appendkey boolean
Default: true

When used with href, passes CFTREEITEMKEY variable
with the value of the selected tree item in URL to the
application page specified in the cfform action
attribute

highlighthref boolean
Default: true

Yes: Highlights links that are associated with a cftreeitem
with a URL attribute value.
No: Disables highlight.

onvalidate string

JavaScript function to validate user input. The form object,
input object, and input object value are passed to the
specified routine, which should return True if validation
succeeds; False, otherwise.

onerror string

JavaScript function to execute if validation fails.

griddataalign string
Default: left

Left: left-aligns data within column.
Right: right-aligns data within column.
Center: center-aligns data within column.
Values:
  • left
  • center
  • right

gridlines boolean
Default: true

Yes: enables row and column rules in grid control

rowheight numeric

Minimum row height, in pixels, of grid control. Used with
cfgridcolumn type = "Image"; defines space for graphics to
display in row.

rowheaders boolean
Default: true

Yes: displays a column of numeric row labels in grid
control

rowheaderalign string
Default: left

Left: left-aligns data within row header
Right: right-aligns data within row header
Center: center-aligns data within row header
Values:
  • left
  • center
  • right

rowheaderfont string

Font of data in column.

rowheaderfontsize numeric

Size of text in column.

rowheaderitalic boolean
Default: false

Yes: displays grid control text in italics

rowheaderbold boolean
Default: false

Yes: displays grid control text in bold

rowheadertextcolor string
Default: black

Text color for control. For a hex value, use the form:
textColor = "##xxxxxx", where x = 0-9 or A-F; use two hash
signs or none.
Values:
  • black
  • red
  • blue
  • magenta
  • cyan
  • orange
  • darkgray
  • pink
  • white
  • lightgray
  • yellow

colheaders boolean
Default: true

Yes: displays a column of numeric row labels in grid
control

colheaderalign string
Default: left

Left: left-aligns data within row header
Right: right-aligns data within row header
Center: center-aligns data within row header
Values:
  • left
  • center
  • right

colheaderfont string

Font of data in column.

colheaderfontsize numeric

Size of text in column.

colheaderitalic boolean
Default: false

Yes: displays grid control text in italics

colheaderbold boolean
Default: false

Yes: displays grid control text in bold

colheadertextcolor string

Text color for control. For a hex value, use the form:
textColor = "##xxxxxx", where x = 0-9 or A-F; use two hash
signs or none.
Values:
  • black
  • red
  • blue
  • magenta
  • cyan
  • orange
  • darkgray
  • pink
  • white
  • lightgray
  • yellow

bgcolor string

Background color of grid control.
Values:
  • black
  • red
  • blue
  • magenta
  • cyan
  • orange
  • darkgray
  • pink
  • white
  • lightgray
  • yellow

selectcolor string

Background color for a selected item.
Values:
  • black
  • red
  • blue
  • magenta
  • cyan
  • orange
  • darkgray
  • pink
  • white
  • lightgray
  • yellow

selectmode string

Selection mode for items in the control.
- Edit: user can edit grid data. Selecting a cell opens
the editor for the cell type.
- Row: user selections automatically extend to the row
that contains selected cell.
- Single: user selections are limited to selected cell.
(Applet only)
- Column: user selections automatically extend
to column that contains selected cell. (Applet only)
- Browse: user can only browse grid data. (Applet only)
Values:
  • edit
  • single
  • row
  • column
  • browse

maxrows numeric

Maximum number of rows to display in grid.

notsupported string
Default: <b>Browser must support Java to <br>view ColdFusion Java Applets!</b>

Text to display if a page that contains a Java applet-based
cfform control is opened by a browser that does not
support Java or has Java support disabled.

picturebar boolean
Default: false

Yes: images for Insert, Delete, Sort buttons

insertbutton string

Text for the insert button. Takes effect only if
selectmode="edit".

deletebutton string

Text of Delete button text. Takes effect only if
selectmode="edit".

sortascendingbutton string

Sort button text

sortdescendingbutton string

Sort button text

style string

Flash only: Must be a style specification in CSS format.
Ignored for type="text".

enabled boolean
Default: true

Flash only: Boolean value specifying
whether the control is enabled. A disabled
control appears in light gray.
Default: true

visible boolean
Default: true

Flash only: Boolean value specifying
whether to show the control. Space that would
be occupied by an invisible control is blank.
Default: true

tooltip string

Flash only: text to display when the
mouse pointer hovers over the control.

onchange string

Flash only: ActionScript to run when the control changes
due to user action in the control.

bindonload boolean
Default: true

* yes: executes the bind attribute expression when first loading the form.
* no: does not execute the bind attribute expression until the first bound event.
Ignored if there is no bind attribute.

selectonload boolean
Default: true

* yes: selects the first row of the grid when the grid loads.
* no: does not select any rows when the grid loads.

onblur string

ActionScript that runs when the grid loses focus.

onfocus string

ActionScript that runs when the grid gets focus.

collapsible boolean

A Boolean value specifying whether the user can collapse the entire grid by clicking an arrow on the title bar.

groupfield string

Puts the grid rows into groups, organized by the column specified in this attribute. Each group is collapsible and has a header with the column name, group field value, and number of entries in the group.

onLoad string

Java Script function that gets called when a grid is loaded for first time

Examples
Sample code using the cfgrid tag

The CFgrid and related tags offer a LOT of capability and many options, but if you just need a very simple demonstration of a working grid, here you go.

<cfform>
                <cfgrid name="grid1" format="html" >
                                <cfgridcolumn name="col1">
                                <cfgridrow data="xxx">
                </cfgrid>
</cfform>

Expected Result: A single-column grid

Signup for cfbreak to stay updated on the latest news from the ColdFusion / CFML community. One email, every friday.

Fork me on GitHub