cfgrid

FORMAT="applet" HAS BEEN DEPRECATED

For a full list of deprecated features, refer to Deprecated features.

Used in the cfform tag. Puts a grid control (a table of data) in a ColdFusion form. To specify grid columns and row data, use the cfgridcolumn and cfgridrow tags, or use the query attribute, with or without cfgridcolumn tags.
For CFC methods that returns numeric data with a leading zero, for example, zip code 02674, the zero is interpreted by the bind expression as an octal number and its decimal equivalent (in this case 1468) even if you set returnformat="string". To resolve this issue, for URL binds or binds routed by way of a JavaScript function (for example, using cfajaxproxy), you can set returnformat=plain to retain the numeric value. Also, leading zeros are stripped from the suggestion list for autosuggest controls.

Category

Forms tags

Syntax

See also

cfajaximport, cfapplet, cfcalendar, cfgridcolumn, cfgridrow, cfgridupdate, cfform, cfformgroup, cfformitem, 

cfinput, cfselect, cfslider, cftextarea, cftree, Using HTML grids in the Developing ColdFusion Applications

History

ColdFusion (2024 release): Changed default value of format to html.

ColdFusion 11 Update 11: Added the attribute resetHead.

ColdFusion 9.0.1: Added the attribute  multirowselect , supported only in HTML grids.

ColdFusion 9:

• Added collapsible,  groupfield , onLoad, and title attributes, supported in HTML grids only.
• Added ability to use the insert attribute in HTML grids.
  ColdFusion 8: Added support for HTML format grids, including the  html  value of the format attribute and the following attributes: bind, bindOnLoad, pageSize, preservePageOnSort, stripeRows, stripeRowColor.ColdFusion MX 7.01: Added support for the onBlur and onFocus events.ColdFusion MX 7:
• Added the format attribute and support for Flash and XML output.
• Added enabled, onChange, style, tooltip, and visible attributes (Flash format only).
  ColdFusion MX: Changed the rowHeaderWidth attribute: ColdFusion does not use the rowHeaderWidth attribute. You can omit it.

Attributes

Usage

Most of the following paragraphs describe grid features that apply to all, or at least two, grid formats. For information that is specific to Flash forms, see Creating Forms in Flash in the Developing ColdFusion Applications. For information that is specific to HTML format grids, see Using HTML grids in the Developing ColdFusion Applications.
This tag must be in a  cfform  tag block. 

You can populate a  cfgrid  with data from a  cfquery . If you do not specify any  cfgridcolumn  tags in the  cfgrid  body, ColdFusion generates a grid with the following:

• A column for each column in the query.

• A default header for each column, created by replacing hyphen or underscore characters in the table column name with spaces. The first character, and any character after a space, are changed to uppercase; all other characters are lowercase.
  This tag requires an end tag.

  Note: Clicking the submit button while editing a grid cell occasionally causes the cell changes to be lost. To ensure that changes are submitted properly, Adobe recommends that after user updates data in a cell, they click another cell before submitting the form.

Returning cfgrid data to the action page

The following information applies to all  cfgrid  formats. Also, HTML format grids can dynamically get data by using a bind expression. For more information, see Using HTML grids in the Developing ColdFusion Applications.
When a user submits a form, the  cfgrid  tag sends information about user actions by setting form variables in the data submitted to the form's action page. Because the data can vary, depending on the tag's SelectMode attribute value, the form variables that are returned also vary depending on this value. In general, the data returned falls into one of these categories:

• Simple data, returned from simple select operations
• Complex data, returned from insert, update, and delete operations

Simple selection data (SelectMode = Single, Column, or Row)

The data that form variables return to the  cfform's action page contains information about which cells the user selected. In general, ColdFusion makes this data available in the action page, as ColdFusion variables in the Form scope, with the naming convention form.#GridName#.#ColumnName#.}}Each {{SelectMode returns these form variables:

Complex update data (SelectMode = Edit)

The grid returns a large amount of data, to inform the action page of inserts, updates, or deletes that the user made to the grid. In most cases, you can use the cfgridupdate tag to automatically gather the data from the form variables; the tag collects data, writes SQL calls, and updates the data source. If you cannot use cfgridupdate (if, for example, you must distribute the returned data to more than one data source), write code to read form variables. In this mode, ColdFusion creates the following array variables in the Form scope for each cfgrid:

Each table row that contains an update, insert, or deletion has a parallel entry in each of these arrays. To view all the information for all the changes, you can traverse the arrays, as in this example. To make it work with a cfgrid on a submitted cfform, set the GridName variable to the name of the grid and the ColNameList to a list of the grid columns.

Using the href attribute

When specifying a URL with grid items using the href attribute, the selectMode attribute value determines whether the appended key value is limited to one grid item or extends to a grid column or row. When a user clicks a linked grid item, a cfgridkey variable is appended to the URL, in this form:

If the appendKey attribute is set to no, no grid values are appended to the URL. The value of selection is determined by the value of the selectMode and attribute:

• If you specify a hrefKey attribute, selection is the field value of the column specified by the attribute. Otherwise, it is one of the following:
• If selectMode="Single", selection is the value of the column clicked.
• If selectMode="Row", selection is a comma-delimited list of column values in the clicked row, beginning with the value of the first cell in the row.
• If selectMode="Column", selection is a comma-delimited list of row values in the clicked column, beginning with the value of the first cell in the column.
  When you use an href attribute, you can also specify a target attribute with any of the standard HTML target specifiers, _blank, _parent, _self, and _top, or with a specific frame name.

Enhancements made in ColdFusion 9.0.1

• In ColdFusion 9, data for the first row is available on form submission in a form with dynamic grid. In ColdFusion 9.0.1, the data is not available.
• If the type is Boolean and selectmode is browse, or select=false, the column is shown as a check box where click does not take effect.

Example

The following example creates a Flash form that displays a set of available courses from the CourseList table in the cfdocexamples database. For more complex examples that use the cfgrid tag, see cfgridcolumn, cfgridrow, and cfgridupdate.