# CFGRID

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.

### Syntax

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

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

#### 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. Valid entries are: Top, Left, Bottom, Baseline, Texttop, Absbottom, Middle, Absmiddle, Right.

#### QUERY

Optional. The name of the query associated with the grid control.

#### INSERT

Optional. Yes or No. Yes allows end users to insert new row data into the grid. Default is No.

#### DELETE

Optional. Yes or No. Yes allows end users to delete row data in the grid. Default is No.

#### SORT

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.

#### FONT

Optional. Font name to use for all column data in the grid control.

#### FONTSIZE

Optional. Font size for text in the grid control, measured in points.

####

#### ITALIC

Optional. Yes or No. Yes presents all grid control text in italic. Default is No.

#### BOLD

Optional. Yes or No. Yes presents all grid control text in boldface. Default is No.

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

#### HREFKEY

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.

#### TARGET

Optional. Target attribute for HREF URL.

#### APPENDKEY

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.

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

#### ONERROR

Optional. The name of a valid JavaScript function you want 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 rules (lines) in the grid control, No suppresses row and column rules. Default is Yes.

#### ROWHEIGHT

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.

#### ROWHEADER

Optional. Yes or No. Yes displays 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 font for row label text in the grid control, measured in points.

#### ROWHEADERITALIC

Optional. Yes or No. Yes presents row label text in italic. Default is No.

#### ROWHEADERBOLD

Optional. Yes or No. Yes presents row label text in boldface. Default is No.

#### ROWHEADERWIDTH

Optional. The width, in pixels, of the row header column.

#### COLHEADERS

Optional. Yes or No. Yes displays column headers in the grid control. Defaults to Yes.

#### COLHEADERALIGN

Optional. Enter Left, Right, or Center to position data within a column header. Default is Left.

#### COLHEADERFONT

Optional. Font to use for the column header in the grid control.

#### COLHEADERFONTSIZE

Optional. Size font for column header text in the grid control, measured in points.

#### COLHEADERITALIC

Optional. Yes or No. Yes presents column header text in italic. Default is No.

#### COLHEADERBOLD

Optional. Yes or No. Yes presents column header text in boldface. Default is No.

#### BGCOLOR

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.

#### 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.
- 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 -- User can only browse grid data.

Default is Browse.

#### MAXROWS

Optional. Specifies the maximum number of rows you want 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 appears:

    <B>Browser must support Java to <BR>
    view ColdFusion Java Applets!</B>

#### PICTUREBAR

Optional. Yes or No. When Yes, image buttons are used for the Insert, Delete, and Sort actions rather than text buttons. 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. The text to use for the Sort button. The default is "`A -> Z`".

#### SORTDESCENDINGBUTTON

Optional. The text to use for the Sort button. The 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.

## Select mode and form variables

Grid data is submitted in a CFFORM as form variables, depending on the value of the SELECTMODE attribute as follows:

- When SELECTMODE="Single", grid data is returned as grid_name.selectedname and the value of the selected cell.
- When SELECTMODE="Column", grid data is returned as a comma-separated list of all the values for the selected column.
- When SELECTMODE="Row", grid data is returned as grid_name.colum1_name and grid_name.column2_name and their respective values for the selected row.
- When SELECTMODE="Browse", no selection data is returned.

## Using SELECTMODE="Edit"

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.

## 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 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="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.

Note | CFGRID incorporates a Java applet, so browsers must be Java-enabled for CFGRID to work properly.

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

    ...