Used inside CFFORM, CFGRID allows you to place a grid control in a ColdFusion form. A grid control is a table of data divided into rows and columns. CFGRID column data is specified with individual CFGRIDCOLUMN tags.
See also CFGRIDROW and CFGRIDUPDATE tags.
<CFGRID NAME="name" HEIGHT="integer" WIDTH="integer" VSPACE="integer" HSPACE="integer" ALIGN="value" QUERY="query_name" INSERT="Yes/No" DELETE="Yes/No" SORT="Yes/No" FONT="column_font" FONTSIZE="size" ITALIC="Yes/No" BOLD="Yes/No" HREF="URL" HREFKEY="column_name" TARGET="URL_target" APPENDKEY="Yes/No" HIGHLIGHTHREF="Yes/No" ONVALIDATE="javascript_function" ONERROR="text" GRIDDATAALIGN="position" GRIDLINES="Yes/No" ROWHEIGHT="pixels" ROWHEADERS="Yes/No" ROWHEADERALIGN="position" ROWHEADERFONT="font_name" ROWHEADERFONTSIZE="size" ROWHEADERITALIC="Yes/No" ROWHEADERBOLD="Yes/No" ROWHEADERWIDTH="col_width" COLHEADERS="Yes/No" COLHEADERALIGN="position" COLHEADERFONT="font_name" COLHEADERFONTSIZE="size" COLHEADERITALIC="Yes/No" COLHEADERBOLD="Yes/No" BGCOLOR="color" SELECTCOLOR="color" SELECTMODE="mode" MAXROWS="number" NOTSUPPORTED="text" PICTUREBAR="Yes/No" INSERTBUTTON="text" DELETEBUTTON="text" SORTASCENDINGBUTTON="text" SORTDESCENDINGBUTTON="text"> </CFGRID>
Required. A name for the grid element.
Optional. Height value of the grid control in pixels.
Optional. Width value of the grid control in pixels.
Optional. Vertical margin spacing above and below the grid control in pixels.
Optional. Horizontal margin spacing to the left and right of the grid control in pixels.
Optional. Alignment value. Valid entries are: Top, Left, Bottom, Baseline, Texttop, Absbottom, Middle, Absmiddle, Right.
Optional. The name of the query associated with the grid control.
Optional. Yes or No. Yes allows end users to insert new row data into the grid. Default is No.
Optional. Yes or No. Yes allows end users to delete row data in the grid. Default is No.
Optional. Yes or No. When Yes sort buttons are added to the grid control. When clicked the sort buttons perform a simple text sort on the selected column. Default is No.
Optional. Font name to use for all column data in the grid control.
Optional. Font size for text in the grid control, measured in points.
Optional. Yes or No. Yes presents all grid control text in italic. Default is No.
Optional. Yes or No. Yes presents all grid control text in boldface. Default is No.
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, then the HREF value that is displayed 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.
Optional. The name of a valid query column when the grid uses a query. The column specified becomes the Key no matter what the select mode is for the grid.
Optional. Target attribute for HREF URL.
Optional. Yes or No. When used with HREF, Yes passes the CFGRIDKEY variable along with the value of the selected tree item in the URL to the application page specified in the CFFORM ACTION attribute. Default is Yes.
Optional. Yes highlights links associated with a CFGRID with an HREF attribute value. No disables highlight. Default is Yes.
Optional. The name of a valid JavaScript function used 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 and False otherwise.
Optional. The name of a valid JavaScript function you want to execute in the event of a failed validation.
Optional. Enter Left, Right, or Center to position data in the grid within a column. Default is Left.
Optional. Yes or No. Yes enables rules (lines) in the grid control, No suppresses row and column rules. Default is Yes.
Optional. Enter a numeric value for the number of pixels to determine the minimum row height for the grid control. Used with CFGRIDCOLUMN TYPE="Image", you can use ROWHEIGHT to define enough room for graphics you want to display in the row.
Optional. Yes or No. Yes displays row labels in the grid control. Defaults to Yes.
Optional. Enter Left, Right, or Center to position data within a row header. Default is Left.
Optional. Font to use for the row label.
Optional. Size font for row label text in the grid control, measured in points.
Optional. Yes or No. Yes presents row label text in italic. Default is No.
Optional. Yes or No. Yes presents row label text in boldface. Default is No.
Optional. The width, in pixels, of the row header column.
Optional. Yes or No. Yes displays column headers in the grid control. Defaults to Yes.
Optional. Enter Left, Right, or Center to position data within a column header. Default is Left.
Optional. Font to use for the column header in the grid control.
Optional. Size font for column header text in the grid control, measured in points.
Optional. Yes or No. Yes presents column header text in italic. Default is No.
Optional. Yes or No. Yes presents column header text in boldface. Default is No.
Optional. Background color value for the grid control. Valid 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.
Optional. Background color for a selected item. See BGCOLOR for color options.
Optional. Selection mode for items in the grid control. Valid entries are:
Default is Browse.
Optional. Specifies the maximum number of rows you want to display in the grid.
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 appears:
<B>Browser must support Java to <BR> view ColdFusion Java Applets!</B>
Optional. Yes or No. When Yes, image buttons are used for the Insert, Delete, and Sort actions rather than text buttons. Default is No.
Optional. Text to use for the Insert action button. The default is Insert.
Optional. Text to use for the Delete action button. The default is Delete.
Optional. The text to use for the Sort button. The default is "A -> Z
".
Optional. The text to use for the Sort button. The default is "Z <- A
".
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.
Grid data is submitted in a CFFORM as form variables, depending on the value of the SELECTMODE attribute as follows:
When SELECTMODE="Edit ", one-dimensional arrays are used to store data about changes to the grid cells. For example, a one-dimensional array is used to store the type of edits made to grid cells:
gridname.RowStatus.Action [ value ]
Where gridname is the name of the CFGRID and action is U, I, or D for Update, Insert, and Delete, respectively.
ColdFusion also maintains both the value of the edited cell and the original value in one-dimensional arrays. You can reference this data in ColdFusion expressions as follows:
gridname.colname[ value ] gridname.original.colname[ value ]
Where gridname is the name of the CFGRID, colname is the name of the column, and value is the index position containing the grid data.
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 whether 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="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.
Note | CFGRID incorporates a Java applet, so browsers must be Java-enabled for CFGRID to work properly. |
<!--- 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> ...