The flexgrid model is used to configure a complex input control that allows users to edit a set data values defined in a series of rows and columns much like a spreadsheet. Internally, flexgrid controls are rendered as html contenteditable tables and are supported by a hidden field that contains xml data that is used to configure the control and house the data to appear in the flexgrid.
Most of the parameters supplied to the flexgrid model configure the appearance and behaviour of the flexgrid. Let's review these parameters now.
This description is used in messages that refer to the flexgrid control. Enter one or two words to identify the flexgrid to users.
If the generated flexgrid class is to be defined within a certain namespace enter it here. This is normally only used when you wish to inherit flexgrids from other sites.
This css class name will be added to the rendered table. This can be used to style the flexgrid.
If the rendered table is to have a fixed height, choose the desired height here. When a height is given, the table will occupy the same height regardless of the number of rows defined in the grid. When the number of rows exceeds what can be shown within the specified height, a scrollbar will be introduced to allow the user to scroll to the rows which are not visible. Use auto if you want the height of the table to grow based on the number of rows that are defined.
This field can be assigned the name of a css class that will be used to style the flexgrid columns.
This field can be assigned the name of a css class that will be used to style the flexgrid rows.
This field can be assigned the name of a css class that will be used to style the flexgrid cells.
If you wish to externalize and/or translate the grid column headings, enter the name of a definition created using the translation model. Inside this definition, column one should define the column names to be translated. Here we see a translation definition used to translate a flexgrid containing five columns named tag, property, contents, leave_open and device.
The Label value will be used to supply the column headings in the flexgrid. Since this translation defines info_head and info_body, these will be used to drop down an infobox on the heading values.
Flexgrids allow a certain number of fixed columns optionally followed by variable columns (which the user can insert and delete). Enter the number of leading (left hand side) columns that are fixed.
Indicate how many columns should be shown by default. This value must be greater than or equal to the number of fixed columns.
If the user is allowed to insert new columns check this option.
Default Column Width
Column widths can be defined at the column level. Use this value to designate a default width for columns that do not specify a width.
Optionally, one of the columns in the flexgrid can be designated as a key column. In such a case, the Key Format field can be used to specify a regular expression that will be used to validate the format of the key. By default, the key must start with a letter (uppercase or lowercase) followed by letters, numbers or underscore. That is, the default regular expression is /^[A-Za-z][A-Za-z0-9_]*$/.
Updatable Heading Row
Check this option if you want to allow the user to enter values into the heading row of the flexgrid by default. This value can be overridden at the flexgrid column level.
If the flexgrid must define a certain number of fixed rows, enter the desired number here. The user will not be able to delete this number of leading fixed rows.
Enter the number of rows to be shown in the flexgrid by default.
If a certain number of rows are required, enter the number here. If the user has not entered at least this many rows, a validation error will be triggered.
Allow Insert Rows
Check this option if the user is allowed to insert new rows into the flexgrid.
th Row Class
If specified, this css class will be assigned to the table heading cells by default. This value can be overridden at the column level.
td Row Class
If specified, this css class will be assigned to the table data cells by default. This value can be overridden at the column level.
Configuring the Flexgrid Columns
The Column Details grid will normally have one row for each column to be shown in the rendered flexgrid. In this section we describe the fields used to configure each column.
Enter the internal name of the column. This must begin with a lowercase letter followed by lowercase letters, numbers or underscores. If this column can be inserted dynamically, enter the column name new().
This is used to indicate how the column will be represented in the rendered XML. Select Key if the column must be unique. Only one column can be designated as a key. Generally, short "code" values are represented as attributes whereas longer values are represented as elements.
Heading UI Control
If the heading is to be implemented as an input control (as opposed to a simple text string), select the name of the control to be used.
Heading or UI Parms
If the heading in implemented as an input control, this field can be used to supply parameters to configure the control. If the heading is not implemented as a UI control, use this column to enter the heading itself. Note that, if your flexgrid uses a translation class, the heading text will be taken from there.
If you wish to override the default Translation Class for certain columns, you can specify an alternate translation class here.
Check this option if you do not want the column to support a drop down information box on the column heading to instruct the user as to the purpose of the column.
If you don't want certain columns to inherit the default width, enter the desired width here.
Select the desired alignment for the contents of the column.
This field can be used to override the default css class to be used for the column heading cell.
This field can be used to override the default css class to be used for the data cells of the column.
If the column is to have a default value, enter it here.
If this column value must be supplied for every row, check this option. Note that key columns are required by default.
If the column values are to be entered using an input (User Interface) control, select the desired control to be used. If no control is indicated, the user will be able to type directly into the table cell.
If a UI Control is indicated, this field can be used to supply parameters to configure the control.
Select this option if the column values are to be protected (read only) by default.
Select this option to override the default setting to indicate whether the user can over type the column heading value.
Validators can be written to implement complex validation for flexgrid column values. To learn more about validators please follow this link.
This property is not yet implemented by will be used to indicate that client side sorting of the column is supported.
Adding a flexgrid to a Form
To add a flexgrid to a form code the following syntax:
This assumes that the name of the field matches that of the flexgrid class to be used. If this is not the case, you must also include the parameter *flexgrid to identify the desired flexgrid class. For example:
Hiding Flexgrids by Default
Sometimes flexgrids are used to show optional information and you may want to hide the flexgrid if it does not contain any information. This can be done by adding a *summary property as in:
If you want to show flexgrids that do not contain any information but allow the user to hide the flexgrid sent the *open property to true.
Interacting With Flexgrids
Flexgrids are implemented as php classes. To read and write flexgrid column and row values you must instantiate a flexgrid object and call its methods.
Instantiating a Flexgrid Object
The following code can be used to instantiate a flexgrid object defined as my_flexgrid.
Loading a Grid from XML
XML is used to load data rows and columns into a flexgrid object. This XML is generally stored within a hidden field on a form. The following method is used to load a flexgrid from xml data stored in $xml and optionally validate the xml. This will return true if the xml was successfully loaded, false otherwise.
Please refer to the class db_object_form_handler_base in the system site under classes/form_handler for examples of interacting with a flexgrid.