Bundles

From CollectiveAccess Documentation
Jump to: navigation, search

Bundles

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 (Available for v1.5) 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 the useHierarchicalBrowser 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 using restrictToTermsRelatedToCollection) type code
Relationship showCurrentOnly If checked only the most recently dated relationship is displayed. set to a non-zero value to enable
Relationship showCurrentUsingDate Set if you'd like to determine the "current' relationship based on a specific date element . metadata code for the chosen date (i.e. ca_objects_x_collections.collection_date)
Relationship allowedSorts Sets the values that are available as optional sorts for the relationship. Note: currently only works for "bubbles" not "lists" metadata element code (including table, i.e. ca_occurrences.venue_type).
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 the bundle 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)

sphinx

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools