The table field type displays and maintain tables of data, in which each row of the table represents a node. It is very powerful, and can be a significant building block for many Metrici applications. There are lots of options to specify what data should be shown and how the table should be managed.
The table field type has a Table tab for defining the table. This is split into five sections:
- Table visibility
- Table columns
- Table rows
- New rows
- Row linking
Table visibility
Tables can be shown in one of two modes: read-only display mode, and updateable edit mode. Either mode can be used on the browse or edit view of the page.
In the visibility section, select which mode you want for the browse page and which mode you want for the edit page. You can also set what headings can be shown.
The standard not entered options are available on the options tab, which you can use to tailor what to show on the browse page if the table is empty.
Table columns
The table columns section specifies the columns for the table.
Columns are specified using views, and different views can be entered for the display and edit mode (remembering that these do not need to correspond to the browse and edit pages). Views can be specified on the field, or a field on the context can be specified from which the view will be read. If both are given, then the view on the context will override that defined on the field.
Instead of specifying a view, you can list a set of fields that should form the columns.
A number of modifications are made to the views:
- If the view does not contain a column with a reference of "open", an additional column is added to the start of the table that provides an open link. In display mode this goes to a browse of the row; in edit mode it edits the row.
- If the view does not contain a column with a reference of "actions", an additional column is added to the end of the table that provides actions. This provides a link to the properties of the node, and, if in edit mode, a link to remove or delete the row.
- On the edit page, links are modified to ensure the page is saved before the navigation is actioned. The links must have a standard link type (link, or an array type with links).
- If appropriate, an additional column is added for sequencing the rows in the table.
The open and actions columns are complicated. They can execute a script automatically added to the node type, and, on the edit page (whether in browse or edit mode, but not on the browse page in edit mode) links are converted to execute buttons formatted as links (see Action scripts). If you want to create your own columns, use the conventions described in the Table Field Action Script.
Table rows
Each row in the table represents one node.
The row nodes are read from a node known as the table source. You can specify the table source in one of three ways:
- You can specify a field on the context which links to the table source.
- You can specify a binding reference that will be used to locate the table source.
- Specify neither, in which case the context node is considered to be the table source.
You can also specify how the rows are calculated from the table source, in one of three ways:
- You can build the rows from all the contents of the source node, i.e. treat the source node as a folder and the rows are all its contents.
- Specify a field that lists the rows.
- Specify neither, in whcih case the table field itself will list the table rows.
New rows
If the table is updatable, you may want to allow the user to add new rows, in which case you need to specify what node types to use and where to put the new rows.
The possible node types can be built from:
- A node type that holds the list of fields in the table columns section, in which case you may want to provide an alternative name for what the item in called.
- A list of node types.
- An option to select other node types.
- A field on the context that lists additional node types.
If you don't select any of these, the user will not have options for creating new rows.
New rows are written to a data folder. This defaults to being the same as the source node, but can be specified using a field on the context or a binding reference, like the source node.
References for new nodes will be assigned automatically. Check the enter reference option If you want the user to be able to set the references themselves.
Row linking
If, within the table source section, you have specified that the table should be built from source content, then the rows from the source node folder will simply be presented in alphabetic sequence. In other cases, the rows will be read from the source field, which defaults to the table field, and which can allow linking other row nodes into the table and managing the order of the rows.
The link type specifies what sort of links should be maintained.
- Normal links allow the table field to link to other nodes.
- Automatic links are used when links don't need to be maintained because the list of rows is built using derivation.
- Private links disallow linking to other nodes, and you can only modify the table by creating and deleting rows.
If you have selected normal links, you can select from where links can be read. This defaults to the data folder, but you can add another link source node, which is specified in the same way as the data folder.
Links will by default be offered to all the nodes within the data folder and source node. However, you can set a link field, in which case this will be used to list a set of possible new links. This can be useful when using tagging and indexing, as it allows you to present for linking only nodes with the correct tags.
As well as the data folder and the link source node, you can select to link to nodes in any other folders.
Lastly, there are options for manually ordering the rows, which apply to both normal and private links. There are important limitations on ordering. Ordering can only be applied where the table source node is the context and the table field is the source field, i.e. when the table rows section is empty. Provided this is the case, you can either switch on row ordering in the field definition, or designate a field on the context that can be used by the user to switch on row ordering.
If you are using manual row ordering, make sure that you do not use a self-sorting table. Otherwise goodness knows what will happen.
Notes
Table update requires execute permission on the context node, in addition to update authority.
Tables are built using derived data. It is possible to use derivation to merge additional nodes into the table which will automatically be added to the original data as the table is updated. This can be useful when you need a table that holds all package content but may include other links and may be ordered.