Compound Objects

A “Compound Object” describes an item that is made up of a set of digital files intended to be treated as one connected item in the collection site and displayed on a single Item page.

Please visit the demo CollectionBuilder-CSV site and demo CollectionBuilder-GH site for examples of compound objects in action, and view the demo compound object metadata sheets for CollectionBuilder-CSV and CollectionBuilder-GH for an example of how compound objects are represented in a metadata spreadsheet.

CollectionBuilder has two built in types of compound object displays: “compound_object” and “multiple”.

Compound objects and multiples can be used in both CollectionBuilder-CSV and CollectionBuilder-GH, but the implementation process is slightly different between the two templates. In CollectionBuilder-CSV, these values (compound_object, multiple, etc) populate the compound object record’s “display_template” field. In CollectionBuilder-GH, they populate the compound object record’s “format” field.

Compound Object Metadata Approach Using “parentid”

Incorporating compound objects requires some additional conventions in your metadata spreadsheet.

For non-compound object collection items, each object is represented by one row in your metadata spreadsheet. Compound objects are different in that they are represented by multiple rows in the metadata: a parent row plus one or more child rows. The parent row describes the compound object Item as a whole, while each child row describes an individual child object within the compound object. The children are connected to the parent through the “parentid” field, which contains a value matching the parent’s “objectid” value.

Ultimately all of the related children rows will be displayed together on a single Item page.

This approach allows each child object to be fully described individually (or not) using any field in your metadata. It is also useful if you are exporting existing metadata from a platform such as CONTENTdm with “page level” metadata. The general convention is flexible and often useful for structuring other custom item types.

parentid Metadata Conventions

To include compound objects the following conventions are used in your metadata spreadsheet:

• Add a “parentid” field to your metadata spreadsheet.
• For non-compound object items and parent items, the “parentid” field will be left blank.
• A parent metadata record is created for each compound object.
  • Parent “parentid” is blank.
  • The parent will use a compound object “display_template” value (compound_object, multiple, image_comparison or other custom type). Note: in CB-GH this value is put in the “format” field instead of “display_template”.
  • The image listed in image_thumb and image_small of the parent will be used to represent the item in all visualizations (In CB-GH it will be an icon only).
  • Parent rows will generate an Item page in your site.
• A child metadata record is created to represent each related sub-item.
  • Child requires a unique “objectid” (like all items)
  • Child requires a “parentid” value that matches their parent’s “objectid”. e.g. If the parent’s “objectid” is example002, then all related children should have example002 in their “parentid” field.
  • Child records will have a value in “display_template” (or “format” for CB-GH) that corresponds to it item type (like a normal item). See options for display_template for CB-CSV and options for format for CB-GH.
  • Child rows will NOT generate an Item page in your site, they will only be pulled into their parent’s Item page.

Display Templates

CollectionBuild provides some built in display_template values that make use of the compound object style metadata structure. These display_template values are applied ONLY to the parent item. Child items will use their own display_template, generally based on their media type (image, pdf, video, etc).

compound_object

A “compound_object” item can include a set of objects with any media type that CollectionBuilder handles, i.e. image, pdf, video, audio, panorama (CB-CSV only), or record.

• Parent items with the display_template (CB-CSV) or format (CB-GH) value of compound_object will generate an Item page featuring a grid of cards representing item thumbnails for each child object. Clicking the child thumbnails opens a child object page as a modal. The child modal has similar features to the display of an individual item page, but maintains the context of the compound object parent.
• “compound_object” use case examples:
  • Scrapbook: to represent a digitized scrapbook, a compound object might contain a series of 25 pages or photographs from a scrapbook. The parent compound object metadata record provides full details about the scrapbook, while the child object metadata records will only describe the unique information about each individual page or photo.
  • Oral history: an oral history compound object might contain various derivatives of an interview, such as audio, video, transcript, and portrait.
  • Gallery: a gallery compound object might contain a series of images from one event that are individually described with independent metadata.

multiple

A “multiple” item is a set of images to be displayed together in a single Item page.

• Parent items with the display_template value (CB-CSV) or format (CB-GH) of multiple will generate an Item page featuring the child objects displayed as a vertical series of large images that scroll down the page. The children do not have individual child object pages/modals. Instead, clicking the child images will open a spotlight gallery of the images. Individual metadata for each child object is not displayed.
• “multiple” use case examples:
  • Postcard: images of a postcard’s front and back that are not individually described in the metadata beyond having a “title” value.
  • 3D archeological artifact: images representing standardized perspectives of an archeological artifact that are not individually described in the metadata beyond having a “title” value (for example, “top”, “bottom”, “side” of a bowl).
  • Gallery: images from a single event that are not individually described in the metadata beyond having a “title” value.

The “multiple” display_template (CB-CSV) or format (CB-GH) works well if the child files do not require their own metadata. By default, only the “title” of the child files will be represented on the item page – all other metadata for child files will be ignored.

image_comparison

A “image_comparison” item is TWO images that are displayed together by stacking them on top of each other and providing a slider to reveal one or the other. The layout uses Before-After Image Comparison Slider, a lightweight web component library for comparing two images, created by markpbaggett for TAMU Library (inspired by Knight Labs’s JuxtaposeJS). This only works with TWO image items, so you will have three rows (parent and 2 children).

• Parent item will have the “display_template” value image_comparison.
  • Fill the metadata fields to describe the comparison.
  • The “object_location” column will be blank.
• The two child records will have “display_template” value image.
  • Fill in the metadata fields as a normal image Item.
  • Child metadata will be displayed in a collapse.

Check the comments at the top of “_layouts/item/image_comparison.html” for front matter options that configure the layout for all “image_comparison” items. There are two main options: “slider” (the image comparison is the main display on the item page) or “side-by-side” (two image thumbs with button to open full screen modal with the image comparison).

Visualization Configuration Options

Configure the “Compound Objects” options in “theme.yml” to add or remove the children of your compound objects on the map, timeline, data, carousel, browse, and search pages.

If a Compound Objects option is set to true, each child item will be individually represented on the corresponding page. If set to false, only the parent record (and its metadata) will appear on the corresponding page. Child objects will still be accessible on the parent’s Item page.