Configuring Relationship Bundles
When placing a Relationship bundle in an editor, such as Related Entities in the Object editor, or Related Occurrence in the Collection editor, the display of related records defaults to displaying the Preferred Label of the record, in a "draggable" bubble. However, there are many ways to configure precisely how relationships are displayed in the User Interface. Using the bundle settings and bundle display templates outlined below, you may configure additional metadata, instead of or in addition to preferred labels, control how this information is sorted, and how it is displayed.
User interface Settings
There are several settings that can be used to configure relationship bundles when they are placed on a user interface screen.
|Alternate label to place on bundle||Custom label text to use for this placement of a specific bundle label. For example, Related Entities may be re-labelled to Related Author, or Related Donor.|
|Alternate label to place on bundle add button||Custom label text to use for the Add button of a bundle placement.|
|Descriptive text for bundle||Descriptive text to use for the Help section of the bundle. This text will override any default help text already configured for the element.|
|Width||Width, in characters or pixels, of element in search form.|
|Height||Height, in characters or pixels, of element in search form.|
|Read only?||If checked, this bundle will not be editable.|
|Restrict to relationship types||Restricts the display to related items only of a certain relationship type, such is is author of/was authored by, or is donor of/was donated by. For no restriction, leave all un-selected.|
|Restrict to types||Restricts the display to records of a certain specified type. Here you could restrict Related Objects to certain Object Types, or Entities to certain Entity types (like author or donor to continue our example.)|
|Do not include sub-types||Usually, restricting to types automatically includes sub-types. Check this box to literally restrict the display to selected type only.|
|Format of relationship list||Choose between Bubbles or List mode. See below for description of each.|
|Sort using||You may sort the display on any available metadata element in the editor of the record type you are relating.|
|Sort direction||Choose either "Ascending" or "Descending" to determine the direction of the sort.|
|Relationship Display Template||See below|
Format of relationship list
The default display format of a relationship bundle are "draggable" bubbles. This format can now be changed to a List format, which is not "draggable." In this view, multiple metadata elements, beyond preferred labels can be displayed.
Here is the standard "bubble" view, where the preferred label of a related entity is displayed:
Here is the list view of a related entity, that is configured to display both the preferred label, and the email address of the entity:
You may sort the relationships by any metadata element that is configured in the editor of the related item. The "Sort using" menu will contain a drop-down list of all available metadata fields to sort the relationships by.
Relationship display template
The relationship display template determines the layout of relationships when in List mode and HTML can be used here. Element code tags with the prefix ^ can be used to represent the value in the template. ^my_element_code. Click here for a detailed guide to bundle display template syntax.
The above example, where preferred labels and email address were displayed, used the following syntax:
Here is another example, this time formatting a related occurrence in an object editor, where Occurrences are restricted to the "Sale" of an Object, and where the relationship display is configured to show the Sale's name, the buyer's name, and the date of sale:
Sold to: ^ca_entities.preferred_labels.display_name
The relationship bundle would look like this in the object editor: