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. Flexgrid Description
This description is used in messages that refer to the flexgrid control. Enter one or two words to identify the flexgrid to users. NamespaceIf 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. Table ClassThis css class name will be added to the rendered table. This can be used to style the flexgrid. Table HeightIf 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. Column PropertiesThis field can be assigned the name of a css class that will be used to style the flexgrid columns. Row PropertiesThis field can be assigned the name of a css class that will be used to style the flexgrid rows. TD PropertiesThis field can be assigned the name of a css class that will be used to style the flexgrid cells. Translation ClassIf 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. Column ConfigurationFixed ColumnsFlexgrids 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. Initial ColumnsIndicate how many columns should be shown by default. This value must be greater than or equal to the number of fixed columns. Insert ColumnsIf the user is allowed to insert new columns check this option. Default Column WidthColumn widths can be defined at the column level. Use this value to designate a default width for columns that do not specify a width. Key FormatOptionally, 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_]*$/. Row ConfigurationUpdatable Heading RowCheck 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. Fixed RowsIf 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. Initial RowsEnter the number of rows to be shown in the flexgrid by default. Required RowsIf 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 RowsCheck this option if the user is allowed to insert new rows into the flexgrid. th Row ClassIf 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 ClassIf 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 ColumnsThe 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. Column NameEnter 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(). XML TypeThis 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 ControlIf 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 ParmsIf 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. Translation ClassIf you wish to override the default Translation Class for certain columns, you can specify an alternate translation class here. No InfoboxCheck 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. Column WidthIf you don't want certain columns to inherit the default width, enter the desired width here. AlignmentSelect the desired alignment for the contents of the column. th ClassThis field can be used to override the default css class to be used for the column heading cell. td ClassThis field can be used to override the default css class to be used for the data cells of the column. Initial ValueIf the column is to have a default value, enter it here. RequiredIf this column value must be supplied for every row, check this option. Note that key columns are required by default. UI ControlIf 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. UI ParametersIf a UI Control is indicated, this field can be used to supply parameters to configure the control. ProtectedSelect this option if the column values are to be protected (read only) by default. Editable HeadingSelect this option to override the default setting to indicate whether the user can over type the column heading value. ValidationsValidators can be written to implement complex validation for flexgrid column values. To learn more about validators please follow this link. SortableThis 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 FormTo add a flexgrid to a form code the following syntax: :field_name,type:flexgrid 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: :field1,type:flexgrid,*flexgrid:my_flexgrid Hiding Flexgrids by DefaultSometimes 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: :field_name,type:flexgrid,*summary:Optional Settings 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 FlexgridsFlexgrids 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 ObjectThe following code can be used to instantiate a flexgrid object defined as my_flexgrid.
Loading a Grid from XMLXML 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. CreditsThe flexgrid control is based on the amazing work of Jos Huybrighs and we are very grateful to him for sharing the JavaScript code for his Flexible Table Editor. |