Opus 2.30 Publisher's Manual: Using Datacards

Purpose

Datacards are another type of article which are used to store data which is broken down into fields. In other words they form a flat file database. You can have as many types of datacard as you like.

A datacard consists one or more "fields", which hold the data and a "mask", the text which is shown around the fields when the datacard is being displayed. Typically this text is labels, headings and formatting information.

Each field has a label. Only the fields are stored within the article. The mask is stored separately - see below. The fields are stored using an XML style mark up scheme, so a typical article might look like this when examined from MySQL (although all on one line, not nicely formatted as it is here:

<directory>
<organisation>Ball Room Dancing</organisation>
<category>dance</category>
<leader>John Smith</leader>
<venue>Community Centre Annexe</venue>
<datetime>Friday 7-9pm</datetime>
<info>All levels welcome</info>
</directory>

The only special handling in this encoding is that "<" and ">" in fields have to be URL encoded (to "%3C" and "%3E") to avoid being mistaken as XML by the parser. This is done transparently by Opus, but you need to be aware of it if you're writing code which accesses the data directly (you can use the function db_data() in data_function.inc to extract the decoded data if that helps).

Defining a Datacard

A datacard is defined by creating a .xdb whose name is the name of the datacard type. The definition is basically the core of an HTML form with additional tags.

For example the datacard in the example above was created using the definition directory.xdb which looks like this:

<datacard title="Village Directory">
<h3>
<input name="organisation" type="text" size="40" maxlength="255" opustype="text">
</h3>
<table>
<opusform>
<tr>
<td>Category:</td>
<td><select name="category" opustype="select">
<option value="none" opusdef>
<option value="church">Churches
<option value="dance">Dancing
<option value="guides">Guides
<option value="scouts">Scouts
</select>
</td>
</tr>
</opusform>

<tr>
<td>Leader:</td>
<td><input name="leader" type="text" size="40" maxlength="255" opustype="text"></td>
</tr>

<tr>
<td>Venue:</td>
<td><input name="venue" type="text" size="40" maxlength="255" opustype="text"
opusdef="Community Centre"></td>
</tr>

<tr>
<td>Date/Time:</td>
<td><input name="datetime" type="text" size="40" maxlength="255" opustype="text"></td>
</tr>

<tr>
<td>Subscriptions:</td>
<td><input name="subs" type="text" size="40" maxlength="255" opustype="text"></td>
</tr>

<tr>
<td>Concessions:</td>
<td><input name="conc" type="checkbox" opustype="checkbox" opusyes="Yes" opusno="No"></td>
</tr>

<tr>
<td valign="top">Information:</td>
<td>
<textarea name="info" cols="50" rows="25" opustype="text">
</textarea>
</td>
</tr>

</table>
</datacard>

Most of this is standard HTML form code. The differences are:

The whole definition must be contained within an <datacard> tag. This has an optional title attribute which is used as a heading when displaying a single datacard. If you don't want the datacard to expire or be embargoed you can disable these features during the entry of datacards by adding embargo and/or expire attributes respectively set to "N".
In your form you can currently use <input> fields of type "text" and "checkbox", <textarea> fields, and single choice <select> fields. Other HTML form fields will give unpredictable results.
The fields you wish to be saved in the article must include an opustype attribute with a value of "text" (for both type "text" and <textarea> fields), "select" or "checkbox" as appropriate.
<input> fields of type "checkbox" must have two additional attributes opusyes and opusno which contain the values to be stored in the datacard if the field is checked or not checked, respectively - so in the example above the field will contain "Yes" if the box is checked and "No" if it's not. Normally, when viewing the datacard, the value stored is displayed but you can make the checkbox display alternative text by specifying opusyesview and opusnoview attributes.
You can use an opusdef attribute to set a default value for the field when creating a new datacard:
1. For <input> fields of type "text" and <textarea> the opusdef attribute's value is simply the text you wish to be the default (see also the section on "Extension to Text Input Fields" below).
2. For <input> fields of type "checkbox" if you want the box checked then opusdef attribute should be set to the same value as the opusyes attribute.
3. For <select> fields you indicate the default by adding an opusdef attribute with any value to the appropriate <option> tag within the <select>.
You can label parts of the datacard which are only shown when it's being updated by surrounding that text by a pair of <opusform> tags. In the example above the "category" field is hidden (it's only used for sorting) when the datacard is displayed.
Similarly you can label parts of the datacard which are only shown when it's being displayed by surrounding that text by a pair of <opusview> tags.
In some cases it's better to split the whole layout into two parts wrapped in <opusform> and <opusview>: see the example in "Hints and Tips" below.

Extensions to Text Input Fields

We have added some extra processing and validation attributes for text input fields. The ones which are generally applicable are:

Attribute Values

opusdef A default value for new datacards.

opuscase If set to "upper" or "lower" then the text input is converted to upper or lower case respectively.

opusfill If set then the field must be filled, and an error will be declared if it's left blank.

opusorder The column position of the field when shown in an article using an Opus {deck} tag. A value of zero indicates the field is not to be shown, values of 1-n indicate the column positions (if no opusorder attributes are set then all fields are shown, in the order the appear in the datacard).

Attribute	Values
opusdef	A default value for new datacards.
opuscase	If set to "upper" or "lower" then the text input is converted to upper or lower case respectively.
opusfill	If set then the field must be filled, and an error will be declared if it's left blank.
opusorder	The column position of the field when shown in an article using an Opus `{deck}` tag. A value of zero indicates the field is not to be shown, values of 1-n indicate the column positions (if no `opusorder` attributes are set then all fields are shown, in the order the appear in the datacard).

HTML only includes a limited range of input fields so we have extended this to support some additional field types for the text type. These are defined by giving a different value to the opustype attribute. In some cases these have additional optional attributes, as detailed below:

opustype Definition

text An ordinary text entry box. You can use the attributes listed above to modify its behaviour.

date Text entered must be a valid date. Optional attributes are:

Attribute Values

opusformat Format in which the date is displayed. By default this is in dd/mm/yy format but you can specify a different format using this attribute thus:

format= How date is formatted

iso ISO format (yyyy-mm-dd)

dmy european style (dd/mm/yy)

mdy american style (mm/dd/yy)

date(format) Using format. See below.

format is a string of characters specifying the format in the style used by the PHP date() function. So if, for example, you have a merge field:
<opusfield name="datewritten" format="date(F jS, Y)"/>
and you wrote the article on 2003-07-02 it will appear in your page as "July 2nd, 2003".

opusdef A default value for the field when creating a new datacard: either a date in ISO format (i.e. yyyy-mm-dd) or the word "now" if you want it to default to today's date.

opusvalid Specifies the validation on the field. By default any date is acceptable or the field can be left blank but you can change that by setting this attribute to:

past date must be in the past

notpast date must not be in the past

future date must be in the future

notfuture date must not be in the future

time Text entered must be a valid time. Optional attributes are:

Attribute Values

opusformat Time at which the time is displayed. By default this is in twelve hour date format e.g. 9:30am but you can specify a different format using the using this attribute thus (note that seconds are not recorded in time fields so "hms" and "hmsa" are of little use here as they will alway show ":00" for the seconds field):

format= How date is formatted

iso ISO format (hh:mm:ss)

hma twelve hour format e.g. 9:30am

hmsa twelve hour format with seconds e.g. 9:30:15am

hma twenty four hour format e.g. 13:30

hmsa twenty four hour format with seconds e.g. 13:30:15

date(format)
time(format) Using format. See below.

format is a string of characters specifying the format in the style used by the PHP date() function. So if, for example, you have a merge field:
<opusfield name="datewritten" format="time(H.i)"/>
and you wrote the article at 2:30pm it will appear in your page as "14.30".

opusdef A default value for the field when creating a new datacard: either a time in ISO format (i.e. hh:mm:ss) or the word "now" if you want it to default to the time at which the user started entering the datacard.

opusvalid Specifies the validation on the field. By default any time is acceptable or the field can be left blank but you can change that by setting this attribute to:

past time must be in the past at the time the datacard is validated

notpast time must not be in the past at the time the datacard is validated

future time must be in the future at the time the datacard is validated

notfuture time must not be in the future at the time the datacard is validated

How Does Opus Use the .xdb File?

Opus renders the article using the .xdb file either as a form, if you're creating or updating datacards, or as plain HTML if you're viewing the datacard contents. Opus removes the tags and attributes it doesn't need, which means that one "mask" covers both creation and viewing. It also makes it easier for the user when creating new datacards, as data entry apes the layout which will be used when the datacard is viewed.

Hints and Tips

If you're using <select> tags to define fields remember that it is the value which is stored in the article, not the text which you see in the select pull down. Although the text in the pull down is shown when the article is viewed this isn't true in the summaries shown against matches in the search engine. Here the value is shown. It therefore makes sense to use values that will make sense to readers.
Remember that it's easy to change the text associated with each value in a <select> field but changing a value will mean updating all the affected datacards.
It's worth remembering when designing new datacards that in the search engine the hyperlink to the datacard article consists of two elements: the datacard title (taken from the title attribute of the <datacard> followed by a colon and a space, and then the value of the first <input> field in the datacard.
In some cases, where the layout of the datacard as displayed is not ideal for data entry purposes you can find you end up with a mass of <opusform> and <opusview> tags. In these situations you may be better off having two layouts, one surrounded by <opusform> tags, the other by <opusview> tags. So that you can embed your input fields into the <opusview> layout there is an additional tag <opusfield> which takes a single attribute name. Here is an example:
```
<datacard title="Publication" embargo="N" expire="N">
<opusform>
<table>
 <tr>
  <td>Title:</td>
  <td><input name="title" type="text" size="40" maxlength="255" opustype="text"></td>
 </tr>
 <tr>
  <td valign="top">Description:</td>
  <td>
   <textarea name="description" cols="50" rows="10" wrap="virtual" opustype="text">
   </textarea>
  </td>
 </tr>
 <tr>
  <td>Image filename:</td>
  <td><input name="cover" type="text" size="20" maxlength="255" opustype="text">
  </td>
 </tr>
</table>
</opusform>
<opusview>
<table>
 <tr>
  <td valign="top" rowspan="2">
   <img src="/apfimg/<opusfield name="cover">" width="100" height="141">
  </td>
  <td valign="top" colspan="2">
   <h2>
   <opusfield name="title">
   </h2>
  </td>
 </tr>
 <tr>
  <td valign="top">Description:</td>
  <td valign="top">
    <opusfield name="description">
  </td>
 </tr>
</table>
</opusview>
</datacard>
```
This example is for a publications database where the user has uploaded an image of the cover, which is shown on the left of the datacard as viewed, with a title and description to the right. The fields are solicited using a "label - field" style layout however.
Doing it like this also ensure that "title" is the first field in the form, so it's used in the page title and in searches (otherwise it would be the image name, as this is higher in the text in the <opusform> version of the page.

Comment on this page