4.2. display tag and mv_metadata

Interchange can store meta information for selected columns of tables in a site's database. This meta information is used when the user interacts with the database. For example, the meta information for a Hide Item field might specify that a checkbox be displayed when the user edits that field, since the only reasonable values are on and off. Or, the meta information might specify a filter on data entered for a Filename field which makes sure that the characters entered are safe for use in a filename.

Widget type specifies the HTML INPUT tag type to use when displaying the field in, say, the item editor.

Width and Height only apply to some of the Widget type options, for instance the Textarea widget.

Label is displayed instead of the internal column name. For example, the category column of the products table might have a label of Product Category.

Help is displayed below the column label, and helps describe the purpose of the field to the user.

Help url can be used to link to a page giving more information on the field.

Lookup can be used when a field is acting like a foreign key into another table. In that case, use some sort of select box as the widget type, and if referencing multiple rows in the destination table, use a multi select box, with colons_to_null as the pre_filter, and :: as the lookup_exclude.

Filter and pre_filter can be used to filter data destined for that field or data read from that field, respectively.

Repeat?: The Interchange back office UI uses the mv_metadata table to discover formatting information for field, table, and view display. The information is kept in fields in the mv_metadata table, and is used to select the display, the HTML input type, the size (height and width where appropriate), label, help text, additional help URL, and default value display.

It works in conjunction with the [display ...] usertag defined in the Interchange UI as well as in specific pages in the UI. The [display] tag has this syntax:

[display table=tablename column=fieldname key=key arbitrary=tag filter=op ...]

In the simplest use, the formatting information for a table form field is called with:

[display table=products column=category key="os28007"]

The mv_metadata table is scanned for the following keys:

 products::category::os28007
 products::category

If a row is found with one of those keys, then the information in the row is used to set the display widget. If no row is found, an INPUT TYPE=TEXT widget is displayed. If the data is all digits, a size of 8 is used, otherwise the size is 60.

If the following row were found (not all fields shown, would be tab-separated in the actual data):

  code                type   width height label     options
  products::category  text   20           Category

Then this would be output:

<INPUT TYPE=text SIZE=20 VALUE="*category*">

If the following row were found:

  code                type   width height label     options
  products::category  select              Category  =none, product=Hardware

Then the following would be output:

        <SELECT NAME=category>
        <OPTION VALUE="">none
        <OPTION VALUE="product">Hardware
        </SELECT>

The standard widget types are:

text

The default. Uses the fields:

    width   size of input box

textarea

Format a <TEXTAREA> </TEXTAREA> pair. Uses the fields:

        width   COLS for textarea
        height  ROWS for textarea

select

Format a <SELECT> </SELECT> pair with appropriate options. Uses the fields:

  height          SIZE for select
  default         Default for SELECTED
  options         Options for a fixed list (or prepended to a lookup)
  lookup          signals a lookup (used as field name if "field" empty)
  field           field to look up possible values in
  db              table to look up in if not current table
  lookup_exclude  regular expression to exclude certain values from lookup