Working with Related Items

When you create a custom item type, you can define fields as being of the type "related item". This provides a connection to one or more database items of any type.

Defining a Related Item Field

To add a related item to a custom item type definition, create a new field and choose Related Item as the item type. Enter any name and label, and then enter the type of the item to which you want to connect in the Type Options field.

As an example, suppose you have a custom item type named Company, which has fields for Name and URL. You have another custom item type called Product, and you want to associate a company with each product.

Add a field to the Product item type, which for the purposes of our example we'll name "manufacturer". Set the field type to Related Item, and enter "company" in the type options field.

The form for a product will then include a pop-up list of all of the companies.

Normally, only a single item can be selected. If you want to enable multiple selection, add an asterisk after the item type name (e.g., company*).

Accessing Related Items

When you want to display the company information, use the <w:get ... /> statement. To display the company name and URL, as in the example above, the code would be:

<p>Company name: <w:get name="manufacturer[0].name" /></p>
<p>Company URL: <w:get name="manufacturer[0].url" /></p>

The "[0]" is necessary when accessing a single item, because there can be multiple items. If you had multiple items, you could access them individually using [0], [1], [2], etc., but more likely you wouldn't know how many there were and would want to repeat some markup for each of them.

Suppose, for example, you have a course catalog. In the item type "class" you have a related item field called "instructor", which connects to the item type "person". Person, in turn, has a field for the person's name.

To display the list of the instructors, you'd use the following code:

<w:for_each in="instructor">
  <w:get name="in.name" />
</w:for_each>

This construct says to repeat the inner statement for each related item in the instructor field. The syntax "in.name" in the inner statement says to get the name field for whichever person record is being accessed in the loop.

Don't Forget the Item Context

To use any of the code above, there must be an item context set, since that's what determines which item is accessed. If you're on an Item Page (a special page type), then the item ID is automatically captured from the page's URL, and you just have to wrap the page's markup in:

<w:kb:item>
  (page contents)
</w:kb:item>

If you're displaying multiple items, typically you'd be on a regular page, and you'd use code something like:

<w:kb:item:each type='book' category='cat'>
  (markup to repeat for each item)
</w:kb:item:each>

which would repeat the code between these two statements for every item of type book that is assigned to the category cat.

Using Related Items with Standard Item Types

You can also define a related item for a standard item type, such as an article. This is typically used if you have created a Person item type and want to connect people to articles as authors, instead of just entering a name in the author field. This makes it possible to show all the items from a particular author, for example.

To define a related item for a standard DB item, you set config settings. The settings are:

If you add an asterisk at the end of the related item type name, then multiple selection is enabled. For example, suppose you created a custom item type called People, and you want to link each article to one of these people; you'd set the related item type for articles to "People". If you wanted to allow multiple people to be associated with each article, you'd set it to "People*".