Bundles

Intro

Bundles are elements that can be placed on UI screens, included in search forms or displays. They can be attributes of a specific element set or database fields intrinsic to a specific item type. Bundles can be functional elements that allow cataloguers to establish relationships between items, add and remove items from sets and manage an item’s location in a larger hierarchy. Bundles are so named because they are essentially black-boxes that encapsulate various functionality.

Below is a break down of the bundle classes and the properties that are particular to each type.

Bundle type	Also known as	Description	Example
Basic bundle	Administrative bundle, Intrinsic bundle	Always present regardless of configuration. Single data entry; does not repeat.	access
Relationship bundle	Related table	Bundles that create relationships between items.	ca_objects
Label bundles	Name or Title bundle	Human-readable short descriptions used for display to identify a record.	preferred_labels
Attribute bundles	Metadata element	Any field created by a user.	ca_attribute_elementcode
Special bundles		Bundles that allow a cataloger to manage an item’s locations in, for example, sets and hierarchies	hierarchy_location

User interface Settings

There are several settings that can be used to configure all bundles, regardless of type, when they are placed on a user interface screen.

Settings	Description	Default	Values
label	Custom label text to use for this placement of this bundle.
add_label	Custom text to use for the add button for the placement of this bundle.
description	Descriptive text to use for help for bundle. Will override descriptive text set for underlying metadata element, if set. Make sure to include a locale specification, i.e. <setting name=”description” locale=”en_US”>XXX</setting>
readonly	If checked, field will not be editable.	0 (not read only)	0 or 1
expand_collapse_value	(Available for v1.5) Controls the expand/collapse behavior when there is at least one value present. While technically available for most bundles, the setting might have no effect for some of the “special” bundles. They have extra settings, see below.	dont_force (default behavior = save expand/collapse state when the user changes it)	dont_force, collapse, expand
expand_collapse_no_value	(Available for v1.5) Controls the expand/collapse behavior when there is no value present. While technically available for most bundles, the setting might have no effect for some of the “special” bundles. They have extra settings, see below.	dont_force (default behavior = save expand/collapse state when the user changes it)	dont_force, collapse, expand

However, there are type-specific settings as well, outlined below.

Bundle type	Settings	Description	Default	Values
Special (hierarchy_location and hierarchy_navigation only)	open_hierarchy	If checked hierarchy browser will be open when form loads.	1 (open)	0 or 1
Special (hierarchy_location and hierarchy_navigation only)	auto_shrink	If enabled hierarchy browser will shrink to height of contents. Version 1.5 and later.	1 (shrink)	0 or 1
Special (hierarchy_location, hierarchy_navigation and ca_objects_history only)	expand_collapse	Controls the expand/collapse behavior for this bundle.	dont_force (default behavior = save expand/collapse state when the user changes it)	dont_force, collapse, expand
Relationship (ca_list_items only)	restrict_to_lists	Restricts display to items from the specified list(s). Leave all unselected for no restriction.		list code
Relationship (ca_list_items, ca_storage_locations, ca_places only)	useHierarchicalBrowser	If set a hierarchy browser will be used to select the related item rather than an auto-completing text field.	0	0 or 1
Relationship (ca_list_items, ca_storage_locations, ca_places only)	hierarchicalBrowserHeight	The height of the hierarchical browser displayed when theuseHierarchicalBrowser option is set.	200px	A pixel dimension ending with ‘px’ (eg. 500px)
Relationship (ca_objects)	restrictToTermsRelatedToCollection	Will restrict checklist to those terms applied to related collections.	0	0 or 1
Relationship (ca_objects)	restrictToTermsOnCollectionWithRelationshipType	Will restrict checklist to terms related to collections with the specified relationship type. Leave all unselected for no restriction.		type code
Relationship (ca_objects)	restrictToTermsOnCollectionUseRelationshipType	Specifies the relationship used to relate collection-restricted terms to this object. (Required if usingrestrictToTermsRelatedToCollection)		type code
Relationship	restrict_to_relationship_types	Restricts display to items related using the specified relationship type(s). Leave all unselected for no restriction.		type code
Relationship	restrict_to_types	Restricts display to items of the specified type(s). Leave all unselected for no restriction.		type code
Relationship	dont_include_subtypes_in_type_restriction	Normally restricting to type(s) automatically includes all sub-(child) types. If this option is checked then the lookup results will include items with the selected type(s) only	0	0 or 1
Relationship	list_format	Format of relationship list.	bubbles	bubbles or list
Relationship	dontShowDeleteButton	If checked the delete relationship control will not be provided.	0	0 or 1
Relationship	minRelationshipsPerRow	Sets the minimum number of relationships that must be catalogued to save.	empty	numeric value
Relationship	maxRelationshipsPerRow	Sets the maximum number of relationships that must be catalogued to save.	empty	numeric value
Relationship	display_template	Layout for relationship when displayed in list (can include HTML). Element code tags prefixed with the ^ character can be used to represent the value in the template. For example: ^my_element_code.	^preferred_labels	Uses thebundle display template syntax
Relationship	colorFirstItem	If set first item in list will use this color.
Relationship	colorLastItem	If set last item in list will use this color.
Relationship or Attribute	sort	Method used to sort related items.	For attributes: use target element code for sort without table or container path i.e. dates_value NOT ca_objects.date.dates_value. To sort on order created do not use the sort setting at all, use only sortDirection. For relationships: use the target element code for sort WITH full table/container path. Use relation_id to set to order created.
Relationship or Attribute	sortDirection	Direction of sort, when not in a user-specified order.	ASC	ASC or DESC
Attribute or Label	usewysiwygeditor	Check this option if you want to use a word-processor like editor with this text field. If you expect users to enter rich text (italic, bold, underline) then you might want to enable this.		0 or 1
Attribute or Label	width	Width of the placement on the UI		pixels or characters
Attribute or Label	height	Height of the placement on the UI		pixels or characters
Relationship or Label	documentation_url	A documentation link for the bundle		URL
Special (ca_objects_history)	full list of settings here	The Object Use History bundle has many settings. See the included link for a full list.

Here’s an example of how some of the settings above would look at the code-level in an xml profile:

<placement code="ca_film">
  <bundle>ca_objects</bundle>
       <settings>
         <setting name="restrict_to_types">film</setting>
         <setting name="label" locale="en_US">Related films</setting>
         <setting name="add_label" locale="en_US">Add film</setting>
       </settings>
</placement>

Display Settings

From /app/models/ca_bundle_displays.php

Global display settings:

Settings	Description	Default	Values
show_empty_values	If checked all values will be displayed, whether there is content for them or not.	1	0 or 1

Bundle display settings for all types:

Settings	Description	Default	Values
label	Custom label text to use for this placement of this bundle.		Text

Type-specific bundle display settings:

Bundle type	Settings	Description	Default	Values
Label, Attribute, Relationship	delimiter	Text to place in-between repeating values.
Label, Attribute	format	Template used to format output.
Label, Attribute	maximum_length	Maximum length, in characters, of displayed information.	100	Characters
Relationship	makeEditorLink	If set name of related item will be displayed as a link to edit the item.	0 (not a link)	0 or 1
Relationship	restrict_to_relationship_types	Restricts display to items related using the specified relationship type(s). Leave all unselected for no restriction.		type code
Relationship	restrict_to_types	Restricts display to items of the specified type(s). Leave all unselected for no restriction.		type code
Relationship	show_hierarchy	If checked the full hierarchical path will be shown.	1 (full hierarchy shown)	0 or 1
Relationship	remove_first_items	If set to a non-zero value, the specified number of items at the top of the hierarchy will be omitted. For example, if set to 2, the root and first child of the hierarchy will be omitted.	0	Integers zero or greater based on hierarchy
Relationship	hierarchy_order	Determines order in which hierarchy is displayed.		ASC (top first) DESC (bottom first)
Attribute	show_empty_values	If checked all values will be displayed, whether there is content for them or not.	1	0 or 1
Attribute	filter	Expression to filter values with. Leave blank if you do not wish to filter values.		^ca_objects.dimensions.Type IN (“with_frame”)

Search Form Settings

Regardless of type, bundles can take the follow setting when they are used in search forms.

Settings	Description	Default	Values
label	Custom label text to use for this placement of this bundle.		Text
width	Width, in pixels, of search form elements.	100px	A pixel dimension ending with ‘px’ (eg. 500px)