ColdFusion Day 58:

ColdFusion Day 58:

================

USING CFGRID TO CREATE GRIDS

The next Java-based field to look at is created with the CFGRID tag. The CFGRID tag is used to create a grid control, or rows and columns, which resembles a spreadsheet or a word processor table.

grids are ideally suited to display the results of a query because they enable the presentation of multiple fields from multiple records in a query. In addition, grids provide an easy way to enable the editing of multiple records from a database when used in conjunction with the CFGRIDUPDATE tag.

FIGURE 14.17: provides an example of a grid control

-------------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------

| 1 | 1 | Danesh | Arman |

| 2 | 2 | Smith | John |

| 3 | 3 | Doe | Jane |

| 4 | 4 | Johnson | Mary |

| 5 | 5 | Danesh | Joe |

| 6 | 6 | Danesh | Kevin |

================================================

These grids can be used in several ways:

* Data presentation

* Data selection

* Data editing

You will consider each of these in turn and then look at additional features of grid controls such as those that control the appearance of elements in the grid.

DATA PRESENTATION

The first step in using a grid control is to present query data in a useful way for browsing. When used this way, data in the grid cannot be selected, and when the form containing the grid is submitted, no data is sent from the grid field.

This is the ideal place to start working with grids because it enables you to learn the mechanics of building grids from your queries without having to deal with some of the complexities inherent in using grids for data selection and editing.

Because grids are useful when working with query result sets, we need to start our discussion of creating grids with a query that you can use in our examples. because you have used the employee data database throughout this chapter, continue to use it here with the following query:

SELECT *

FROM Employees

ORDER BY ID

</CFQUERY>

Given this query, you can build a simple grid fro browsing the data in this query result by using the CFGRID and CFGRIDCOLUMN tags. CFGRID is used to create the grid by specifying at a minimum the name of the grid, the query to use, and a selection mode. In the case of a grid for displaying data for browsing, you want to use SELECTMODE="Browse", which indicates that the grid is for viewing data and that selection is not possible:

Next you need to indicate which fields to display and in which order. You use CFGRIDCOLUMN to do this because the fields are displayed in columns with each record taking a single row. For each field you want to display, you use a single CFGRIDCOLUMN tag. Therefore, to display a person's ID number, Last name, and First name, you would use the following tags:

Here the NAME attribute specifies the name of the field from the query result set that should be used to populate the column. The results are shown earlier in Figure 14.17. The complete code for the grid looks like this:

</CFGRID>

Similarly, if you want a person's name and salary to be displayed, you might use:

</CFGRID>

and you would get results like those in Figure 14.18.

FIGURE 14.18: Displaying employee information in a grid

-------------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------

| 1 | Danesh | Arman | 10000 |

| 2 | Smith | John | 7500 |

| 3 | Doe | Jane | 6200 |

| 4 | Johnson | Mary | 9900 |

| 5 | Danesh | Joe | 10000 |

| 6 | Danesh | Kevin | 10000 |

================================================

The first thing you probably noticed in both grids is that the column headers are the names of the fields. this can be less than ideal. For instance, LastName and FirstName should appear as last Name and First Name, and Salary might be more descriptive as Monthly Salary.

These changes can be achieved by using the HEADER attribute of the CFGRIDCOLUMN tag to specify alternate column headers:

</CFGRID>

This produces the grid shown in Figure 14.19.

FIGURE 14.19: Using alternate column headers

-------------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------

| 1 | Danesh | Arman | 10000 |

| 2 | Smith | John | 7500 |

| 3 | Doe | Jane | 6200 |

| 4 | Johnson | Mary | 9900 |

| 5 | Danesh | Joe | 10000 |

| 6 | Danesh | Kevin | 10000 |

================================================

Another problem with the salary grid is the way in which the numeric values in the salary column are displayed. Numeric values should be aligned to the right side of the column so that the digits align correctly. This is achieved by using the CFGRIDCOLUMN tag's DATAALIGN attribute, which can specify three possible alignments for the data in a column: Left, Centre, and Right. The default alignment for a column is left aligned.

For the salary column, you will want to use the following tag:

Another aspect of presenting salaries is to present them in proper currency format, such as $1000.00. You can achieve this by using the NUMBERFORMAT attribute of the CFGRIDCOLUMN tag. This attribute takes as its value a mask defining how the number should be displayed. This mask uses the same syntax and special characters as NUMBERFORMAT function discussed in Chapter 11, "Grouping, Nesting and Formatting Output".

To present your salaries in a standardized currency format, you could use the numeric mask $__,__.00. Therefore, your final tag is:

This produces the grid in Figure 14.20.

FIGURE 14.20: Formatting numbers with a mask

-------------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------

| 1 | Danesh | Arman | $10000.00|

| 2 | Smith | John | $7500.00|

| 3 | Doe | Jane | $6200.00|

| 4 | Johnson | Mary | $9900.00|

| 5 | Danesh | Joe | $10000.00|

| 6 | Danesh | Kevin | $10000.00|

================================================

NOTE Although it is visually more desirable to specify data alignment on a per-column basis, you can change the default data alignment for the entire grid by using the GRIDDATAALIGN attribute of the CFGRID tag. The value specified with this attribute can be overridden with the DATAALIGN attribute of the CFGRIDCOLUMN tag.

Back Next