CFML Reference
ColdFusion Tags

cfgrid

Description

Used inside cfform, cfgrid lets you place a grid control in a ColdFusion form. A grid control is a table of data divided into rows and columns. The cfgrid tag column data is specified with cfgridcolumn tags.

Category

Forms tags

Syntax

<cfgrid name = "name"

  height = "integer"

  width = "integer"

  autoWidth = "Yes" or "No"

  vSpace = "integer"

  hSpace = "integer"

  align = "value"

  query = "query_name"

  insert = "Yes" or "No"

  delete = "Yes" or "No"

  sort = "Yes" or "No"

  font = "column_font"

  fontSize = "size"

  italic = "Yes" or "No"

  bold = "Yes" or "No"

  textColor = "Web color"

  href = "URL"

  hrefKey = "column_name"

  target = "URL_target"

  appendKey = "Yes" or "No"

  highlightHref = "Yes" or "No"

  onValidate = "javascript_function"

  onError = "text"

  gridDataAlign = "position"

  gridLines = "Yes" or "No"

  rowHeight = "pixels"

  rowHeaders = "Yes" or "No"

  rowHeaderAlign = "position"

  rowHeaderFont = "font_name"

  rowHeaderFontSize = "size"

  rowHeaderItalic = "Yes" or "No"

  rowHeaderBold = "Yes" or "No"

  rowHeaderTextColor = "Web color"

  rowHeaderWidth = "col_width"

  colHeaders = "Yes" or "No"

  colHeaderAlign = "position"

  colHeaderFont = "font_name"

  colHeaderFontSize = "size"

  colHeaderItalic = "Yes" or "No"

  colHeaderBold = "Yes" or "No"

  colHeaderTextColor = "Web color"

  bgColor = "Web color"

  selectColor = "Web color"

  selectMode = "mode"

  maxRows = "number"

  notSupported = "text"

  pictureBar = "Yes" or "No"

  insertButton = "text"

  deleteButton = "text"

  sortAscendingButton = "text"

  sortDescendingButton = "text">

 

</cfgrid> 

See also

cfapplet, cfform, cfinput, cfselect, cfslider, cftextinput, cftree, cfgridcolumn, cfgridrow, cfgridupdate

Attributes

Attribute	Description
name	Required. A name for the grid element.
height	Optional. Height value of the grid control, in pixels.
width	Optional. Width value of the grid control, in pixels.
autoWidth	Optional. Yes or No. Default is No. If Yes, automatically sets the width of each column so that all the columns are visible within the grid's specified width. All columns are initially set to equal widths. Users can resize any column. No horizontal scroll bars are available since all columns are visible. Note that if you explicitly specify the width of a column and set autoWidth to Yes, ColdFusion will set the column to the explicit width, if possible.
vSpace	Optional. Vertical margin spacing above and below the grid control, in pixels.
hSpace	Optional. Horizontal margin spacing to the left and right of the grid control, in pixels.
align	Optional. Alignment value. Options are: Top, Left, Bottom, Baseline, Texttop, Absbottom, Middle, Absmiddle, Right.
query	Optional. Name of the query associated with the grid control.
insert	Optional. Yes or No. Yes lets end users insert row data into the grid. Default is No.
delete	Optional. Yes or No. Yes lets end users delete row data from the grid. Default is No.
sort	Optional. Yes or No. If Yes, sort buttons are added to the grid control. When clicked, sort buttons perform a simple text sort on the selected column. Default is No. Note that columns are sortable by clicking the column head, even if no sort button is displayed.
font	Optional. Font to use for column data in the grid control.
fontSize	Optional. Font size for text in the grid control, in points.
italic	Optional. Yes or No. Yes displays grid control text in italic. Default is No.
bold	Optional. Yes or No. Yes displays grid control text in boldface. Default is No.
textColor	Optional. Color value for text in the grid control. Options 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 two pound signs or no pound signs.
href	Optional. URL to associate with the grid item or a query column for a grid that is populated from a query. If href is a query column, the href value is populated by the query. If href is not recognized as a query column, it is assumed that the href text is an actual HTML href.
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. Target attribute for href URL.
appendKey	Optional. Yes or No. When used with href, Yes passes query string value of the selected tree item in the URL to the application page specified in the cfform action attribute. Default is Yes.
highlightHref	Optional. Yes highlights links associated with a cfgrid with an href attribute value. No disables highlight. Default is Yes.
onValidate	Optional. The name of a JavaScript function used to validate user input. The form object, input object, and input object value are passed to the routine, which should return True if validation succeeds and False otherwise.
onError	Optional. The name of a JavaScript function to execute in the event of a failed validation.
gridDataAlign	Optional. Enter Left, Right, or Center to position data in the grid within a column. Default is Left.
gridLines	Optional. Yes or No. Yes enables row and column rules (lines) in the grid control. No suppresses rules. Default is Yes.
rowHeight	Optional. Number of pixels for the minimum row height of the grid control. Used with cfgridcolumn type = "Image", you can use rowHeight to define enough space for graphics to display in the row.
rowHeaders	Optional. Yes or No. Yes displays a column of numeric row labels in the grid control. Defaults to Yes.
rowHeaderAlign	Optional. Enter Left, Right, or Center to position data within a row header. Default is Left.
rowHeaderFont	Optional. Font to use for the row label.
rowHeaderFontSize	Optional. Size for row label text in the grid control, in points.
rowHeaderItalic	Optional. Yes or No. Yes displays row label text in italic. Default is No.
rowHeaderBold	Optional. Yes or No. Yes displays row label text in boldface. Default is No.
rowHeaderTextColor	Optional. Text color value for the grid control row headers. Entries are: black (default), magenta, cyan, orange, darkgray, pink, gray, white, lightgray, yellow. A hex value can be entered in the form: rowHeaderTextColor = "##xxxxxx" Where x is 0-9 or A-F. Use two pound signs or no pound signs.
rowHeaderWidth	Optional. The width, in pixels, of the row header column.
colHeaders	Optional. Yes or No. Yes displays column headers in the grid control. Default is Yes.
colHeaderAlign	Optional. Enter Left, Right, or Center to position data within a column header. Default is Left.
colHeaderFont	Optional. Font for the column header in the grid control.
colHeaderFontSize	Optional. Size for column header text in the grid control, in points.
colHeaderItalic	Optional. Yes or No. Yes displays column header text in italic. Default is No.
colHeaderBold	Optional. Yes or No. Yes displays column header text in boldface. Default is No.
colHeaderTextColor	Optional. Color value for the grid control column headers. Valid 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.
bgColor	Optional. Background color value for the grid control. Entries are: black, magenta, cyan, orange, darkgray, pink, gray, white, 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.
selectColor	Optional. Background color for a selected item. See bgColor for color options.
selectMode	Optional. Selection mode for items in the grid control. Valid entries are: Edit    Users can edit grid data. Selecting a cell opens the appropriate editor for that cell type. Single    User selections are confined to the selected cell. Row    User selections automatically extend to the row containing selected cell. Column    User selections automatically extend to column containing selected cell. Browse    (default) User can only browse grid data. Cell selection is disabled.
maxRows	Optional. Specifies the maximum number of rows to display in the grid.
notSupported	Optional. The text you want to display if the page containing a Java applet-based cfform control is opened by a browser that does not support Java or has Java support disabled. For example: notSupported = "<B> Browser must support Java to view ColdFusion Java Applets</B>" By default, if no message is specified, the following message displays: <B>Browser must support Java to <BR> view ColdFusion Java Applets!</B>
pictureBar	Optional. Yes or No. If Yes, images are used for the Insert, delete, and Sort buttons rather than text. Default is No.
insertButton	Optional. Text to use for the Insert action button. The default is Insert.
deleteButton	Optional. Text to use for the delete action button. The default is delete.
sortAscendingButton	Optional. Text to use for the Sort button. Default is "A -> Z".
sortDescendingButton	Optional. Text to use for the Sort button. Default is "Z <- A".

Usage

You can populate a cfgrid with data from a cfquery. If you do not specify any cfgridcolumn entries, a default set of columns is generated. Each column in the query is included in the default column list. In addition, a default header for each column is created by replacing any hyphen (-) or underscore (_) characters in the table column name with spaces. The first character and any character after a space is changed to uppercase; all other characters are lowercase.

How data is returned from cfgrid

The cfgrid tag returns data by setting specific form variables in the data submitted to the form's ACTION page, just as a standard HTML form control does. With cfgrid, the data submitted reflects changes and selections the user has made within the grid. Since this data can vary depending on the tag's SelectMode attribute, the form variables returned also vary depending on this attribute's setting.

In general, the data returned falls into one of two categories. Data returned which reflects simple selection operations, and more complex data returned from insert, update and delete operations.

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

If the SelectMode attribute equals Single, Column, or Row, the data returned by form variables to the cfform's ACTION page contains information about which cell or cells were selected by the user. In general, this data is made available by ColdFusion in the ACTION page as ColdFusion variables in the form scope using the following naming convention:

form.#GridName#.#ColumnName#.

Specifically, each SelectMode returns the following form variable(s):

• SelectMode="single"

  form.#GridName#.#ColumnName# = "SelectedCellValue"

• SelectMode="column"

  form.#GridName#.#ColumnName# = "ValueOfCellRow1, ValueOfCellRow2, ... ValueOfCellRowN"

• SelectMode="row"

  form.#GridName#.#Column1Name# ="ValueOfCellInSelectedRow"

  form.#GridName#.#Column2Name# = "ValueOfCellInSelectedRow"

  form.#GridName#.#ColumnNName# = "ValueOfCellInSelectedRow"

Update data (SelectMode = Edit)

If SelectMode attribute is Edit, the grid returns a great deal of data in order to inform the ACTION page of any inserts, updates or deletes that the user has made to the grid. In most cases, you will not need to manually process this data, but can just use the cfgridupdate tag to automatically gather the data from the various form variables. In fact, cfgridupdate not only collects the incoming data but can also write the appropriate SQL calls, and updates your data source.

If you are unable to use cfgridupdate (if, for example, you need to distribute the returned data to more than one data source,) you will need to write code to read the appropriate form variables. In this mode ColdFusion creates three array variables in the form scope for each cfgrid, named:

form.#GridName#.#ColumnName#

form.#GridName#.original.#ColumnName#

form.#GridName#.RowStatus.Action

Each row of the table that contains an update, insert, or deletion has a parallel entry in each of these three arrays. To view all the information for all the changes, you can traverse the three arrays as in the following example.

<CFLOOP INDEX="ColName" LIST="#ColNameList#">

  <CFIF IsDefined("form.#GridName#.#ColName#")>  

    <CFOUTPUT><BR>form.#GridName#.#ColName#:<BR></CFOUTPUT>

    

    <CFSET Array_New    = evaluate("form.#GridName#.#ColName#")>

    <CFSET Array_Orig   =

evaluate("form.#GridName#.original.#ColName#")>

    <CFSET Array_Action =

evaluate("form.#GridName#.RowStatus.Action")>

    

    <CFIF NOT IsArray(Array_New)>

      <B>The form variable is not an array!</b><BR>

      

    <CFELSE>

      <CFSET size = ArrayLen(Array_New)>

      <CFOUTPUT> 

      Result Array Size is #size#.<BR>

      Contents:<BR>

      </CFOUTPUT>

      

      <CFIF size IS 0>

        <B>The array is empty.</B><BR>

        

      <CFELSE>

        <TABLE BORDER="yes">

          <TR> 

<TH>Loop Index</TH>

<TH>Action</TH> 

<TH>Old Value</TH> 

<TH>New Value</TH>

          </TR>

          <CFLOOP index="LoopCount" from="1" to=#size#>  

               <CFSET Val_Orig   = Array_Orig[#LoopCount#]>  

              <CFSET Val_New    = Array_New[#LoopCount#]>  

          <CFSET Val_Action = rray_Action[#LoopCount#]>  

          <CFOUTPUT>

          <TR>

            <TD>#LoopCount#</TD>

 <TD>#Val_Action#</TD>

 <TD>#Val_Orig#</TD>

 <TD>#Val_New#</TD>

          </TR>

          </CFOUTPUT>

          </CFLOOP>

        </TABLE>        

      </CFIF>      

    </CFIF>  

  <CFELSE>

    <CFOUTPUT>form.#GridName#.#ColName#:   NotSet!</cfoutput><BR>  

  </CFIF>  

</CFLOOP>

Using the href attribute

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

http://myserver.com?cfgridkey = selection

If the appendKey attribute is set to No, then no grid values are appended to the URL.

The value of selection is determined by the value of the selectMode attribute:

• When selectMode = "Single", selection is the value of the column clicked.
• When selectMode = "Row", selection is a comma-separated list of column values in the clicked row, beginning with the value of the first cell in the selected row.

When selectMode = "Column", selection is a comma-separated list of row values in the clicked column, beginning with the value of the first cell in the selected column.

Example

<!--- This example shows the cfgrid, cfgridcolumn, cfgridrow,

and cfgridupdate tags in action --->



<!--- use a query to show the useful qualities of cfgrid --->



<!--- If the gridEntered form field has been tripped,

perform the gridupdate on the table specified in the database.

Using the default value keyonly = yes allows us to change only

the information that differs from the previous grid --->

<cfif IsDefined("form.gridEntered") is True>

  <cfgridupdate grid = "FirstGrid" dataSource = "cfsnippets" 

  tableName = "CourseList" keyOnly = "Yes">

</cfif>



<!--- query the database to fill up the grid --->

<cfquery name = "GetCourses" dataSource = "cfsnippets">

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>Try adding a course to the database, and then deleting it.</I>

<!--- call the cfform to allow us to use cfgrid controls --->

<cfform action = "cfgrid.cfm" method = "POST" enableCAB = "Yes">



<!--- We include Course_ID in the cfgrid, but do not allow

for its selection or display --->

<!--- cfgridcolumn tags are used to change the parameters

involved in displaying each data field in the table--->



<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 name = "CorDesc" header = "Description"

    headerAlign = "LEFT" dataAlign = "LEFT" 

    bold = "No" italic = "No"

    select = "Yes" display = "Yes" 

    headerBold = "No" headerItalic = "No">



</cfgrid>



...

Copyright © 2001, Macromedia Inc. All rights reserved.

---