Hierarchies and Collections

Some document collections are structured hierarchically. VuFind® offers a mechanism for displaying these hierarchies as a pop-up within search results and as a tab of the record page.

To display hierarchies, VuFind® needs to be able to find information about document relationships in your Solr index. At index time, you need to populate the following fields in order to use hierarchy functionality:

• hierarchytype - The type of hierarchy being used (this triggers loading of a hierarchy driver; it is usually easiest to leave it blank, causing VuFind® to default to the driver specified in the [Hierarchy] section of config.ini).
• hierarchy_browse - Optional, see Setting Up Browsing below.
• hierarchy_top_id - The Solr ID of the record representing the top of the hierarchy containing the current record.
  • This may be multi-valued if a record belongs to multiple collections.
• hierarchy_top_title - The title of the record representing the top of the hierarchy containing the current record.
  • This may be multi-valued if a record belongs to multiple collections; the order of multiple values in this field must correspond with values in hierarchy_top_id.
• hierarchy_parent_id - The Solr ID of the record immediately above the current record in the hierarchy.
  • This may be multi-valued in the case of multiple collection membership.
• hierarchy_parent_title - The title of the record immediately above the current record in the hierarchy.
  • This may be multi-valued if a record belongs to multiple collections; the order of multiple values in this field must correspond with values in hierarchy_parent_id.
• hierarchy_sequence - A value indicating the position of the current record relative to its siblings, used for sorting records when rendering trees.
  • This may be multi-valued if a record belongs to multiple collections; the order of multiple values in this field must correspond with values in hierarchy_parent_id.
  • Note that this is a string field, so sorting is done alphabetically rather than numerically – numeric values may need to be padded with zeroes to achieve appropriate sorting.
• is_hierarchy_id - If the current record represents a node within a hierarchy, this field should contain the same value as the regular id field.
• is_hierarchy_title - If the current record represents a node within a hierarchy, this field should contain the same value as the regular title field.
• title_in_hierarchy - Optional, introduced in VuFind® 2.3. If a record needs to have a different display title in different collection contexts, this field should contain a number of titles equal to the number of parent collections and in the same order as the hierarchy_parent_id field.

This optional field is not required, but can be used to enhance some functionality:

• hierarchy_all_parents_str_mv - This should contain every parent collection ID – hierarchy_top_id, hierarchy_parent_id, and any “breadcrumb trail” in between. If populated, starting with VuFind® 10.0, this can be used to improve “deep searching” behavior in the collection view by turning on the search_container_id_field setting in HierarchyDefault.ini. Note that any field name can be used in the configuration, so this name is just a suggestion.

Once the Solr index is populated appropriately, you need to adjust several VuFind® configuration files to make hierarchies visible.

• In config.ini, make sure that the [Hierarchy] section contains a driver setting (Default is usually the best option if you want to show trees) and the showTree setting is true.
• In your hierarchy driver configuration file (usually HierarchyDefault.ini in the same directory as config.ini), make sure that appropriate values are set.
• If you are using Solr to construct tree data, you may also want to set up util/createHierarchyTrees.php as a cron job or as part of your index process to ensure that your tree cache is always filled. This will prevent users from experiencing long waits while trees are constructed on demand. If using this approach, be sure your HierarchyDefault.ini has an appropriate solrCacheTime value set (probably -1, for no expiration, if you set things up so that the cache is always populated with appropriate data).
• You can optionally enable or disable searching within trees (a search causes items within the tree to highlight if they match the query); this is on by default and can be controlled within the [Hierarchy] section of config.ini.

Beginning with version 2.4 it is also possible to use the hierarchy support for simple links between containers and their contents. This is typically useful when the full hierarchy support would be overkill. Here it is assumed that the hierarchy is shallow and there are only containers and their child records (e.g. journal and articles). In practice the simple link support does two things:

1. Replaces the linking from a child record to container by title with linking by record ID.
2. Displays the number of child records in the container record page with a link to find them all.

Simple links require only a subset of hierarchy fields:

1. The container record must have is_hierarchy_id
2. The child records must have hierarchy_parent_id
3. Additionally, the child records must have container_title for the link to container to be displayed.
4. Child records may also have container_reference which is displayed after the link and may include e.g. issue and page number.

If the prerequisites above are fulfilled, the simple links can be enabled by setting simpleContainerLinks to true in [Hierarchy] section of config.ini.

Once you have hierarchies set up, you have the option of enabling VuFind®'s Collection module. This can be used to provide an alternative to the standard record view for records that are considered “collections”. This allows you to, for example, view and search a list of items below the collection record's position in the hierarchy.

VuFind®'s collection browse mode also gives you a high-level view of all the records configured to be treated as collections.

To enable collections, set the collections setting in the [Collections] section of config.ini to true.

The collection view is actually a hybrid between a record view and a search results screen. You can customize this view using recommendation modules just like any other search. The relevant configuration options can be found in the Collection.ini file, which lives in the same place as config.ini.

Additional collection-related options can be found in the [Collections] section of config.ini and are documented there with comments.

Further configuration options can be found in your hierarchy driver configuration file (usually HierarchyDefault.ini in the same folder as config.ini). The most important option here is link_type in the [Collections] section. This controls which records are treated as collections rather than flat records. Three options are possible:

• Top - Only records at the top of a hierarchy tree are treated as collections. All nodes below the top are “flattened” into a single result list within the collection.
• All - Any record marked as a node within the hierarchy (i.e. with is_hierarchy_id set in the Solr index) will be treated as a collection. When viewing the collection, only records immediately beneath this node will be visible, allowing a more granular exploration of the hierarchy.
• None - This disables collections for all records using this hierarchy driver. If you only have one hierarchy driver (the most common situation), it is easier to turn off collections globally in config.ini. This setting exists in case it is needed in more complex multi-driver scenarios.

In addition to the custom collection view, VuFind® also offers a module for browsing through lists of your collections. This can be found at Collections/Home under your VuFind® base URL.

In order to browse collections, you need to populate the hierarchy_browse field of your Solr index. This field contains a collection title concatenated with a collection ID, with a delimiter in between. The default delimiter is “<html>id}</html>” but this can be configured to a different string in the [Collections] section of config.ini. The exact collection IDs/titles that should be indexed here depends on how you are Identifying Collections. If your collection identifier is “Top” then collection_browse should contain hierarchy_top_id / hierarchy_top_title values; if your collection identifier is “All” then collection_browse should contain hierarchy_parent_id / hierarchy_parent_title values.

Examples:

Collection identifier = “Top” (only top-level collections are treated as “real” collections)

hierarchy_top_id = 1234
hierarchy_top_title = My Collection
hierarchy_browse = My Collection{{{_ID_}}}1234

Collection identifier = “All” (all records with children in the hierarchy are treated as “real” collections)

hierarchy_parent_id = 1234
hierarchy_parent_title = My Collection
hierarchy_browse = My Collection{{{_ID_}}}1234

By default, the collection browse uses Solr faceting to find a list of collections. However, if you have a large number of collections in your index, this may become slow or take up too much memory. In that case, you can switch to using the alphabetical heading browse mechanism instead by changing the browseType setting in the [Collections] section of config.ini to “Alphabetical.” When using this option, be sure to maintain your browse index databases as described on the alphabetical heading browse page.