Use Metadata Collections

Canopy generates new IIIF Collections based on the metadata labels included in your config/canopy.json file. For each unique string value associated with the label across IIIF Manifests found in your project, a new IIIF Collection is created. These Collections are used to create facets across your site and are also available for reuse in custom content.

💡

This guide assumes you have a Canopy IIIF project. See the Create a Project guide to get started.

Use Case

You are a researcher creating a digital scholarship project and would like to add a custom content page with a Slider component that displays all the works in your collection that have a "Subject" of "War pensions".

  "metadata": [
    {
      "label": {
        "en": [
          "Subject"
        ]
      },
      "value": {
        "en": [
          "War pensions",
          "Tennessee--Politics and government--To 1865"
        ]
      }
    }
  ]

Implementation

Add Metadata Labels to the metadata Property of your Config

In order for Canopy to generate a Collection for a given metadata label, you must add the label to the metadata property in your config/canopy.json file. The metadata property is an array of metadata labels that match string values in your Manifest URI metadata entries.

Since you need a Collection for the Subject label with value of "War pensions", you need to add the label to your metadata array if it's not already there.

config/canopy.json

{
  "collection": "https://digital.lib.utk.edu/assemble/collection/collections/tdh",
  "metadata": ["Subject", "Place", "Format", "Date"]
}

Validate that the Collection was Generated

If you have defined NEXT_PUBLIC_BASE_PATH in your .env file, you will need to include that pattern in your URI.

IIIF Collections are generated when your site is rebuilt or when your server is restarted. After you've added the metadata label to your config/canopy.json file, you should make sure your collection exists. If you are working directly in GitHub with GitHub Pages, you can commit the change and wait for the site to rebuild. If you are working locally, you will need to stop your local server:ctrl + c and then npm run dev to restart your local server.

Once your site is running, you can check that the IIIF Collection was generated by visiting the Collection URI in your browser. Canopy uses the slugify (opens in a new tab) package when generating IIIF Collections. In this process, both the metadata label and metadata value are slugified to create the route to you collection. Slugifying is beneficial for search engine optimization and readability.

The pattern for the URI for your Collection will be your site's base path followed by /api/facet/${facet.slug}/${value.slug}.json. In this example, the Collection URI would be /api/facet/subject/war-pensions.json.

Example Generated Collection

Add the Collection to your Custom Content

Now that you have confirmed the generated Collection is available, you can add it to your custom content. Let's say you want to use the Collection in a Slider component on a custom content page called history in the about section of your site. You would create or modify the file according to the Create Markdown Content Guide and add the Slider component where you want it to appear on the page with your Collection URI as the value of the iiifContent attribute.

content/about/history.mdx

---
title: History
navigation: "about"
---
 
# War Pensions
 
During the American Civil War, the issue of war pensions emerged as a crucial aspect of post-conflict reconstruction. As
the nation grappled with the devastating aftermath of the war, the U.S. government recognized the need to support the
veterans who had sacrificed their well-being for the Union or the Confederacy. War pensions, providing financial
assistance and support to disabled veterans, widows, and orphans, became a cornerstone of the post-war social contract.
The Pension Acts of 1862 and 1864 marked significant legislative milestones, establishing the framework for compensating
soldiers and their families for injuries, disabilities, and loss of life incurred during the conflict. These early
pension initiatives laid the foundation for the more comprehensive pension system that would evolve in subsequent
decades, reflecting the government's commitment to honoring and caring for those who bore the burdens of the Civil War.
 
## Explore Works Related to War Pensions
 
<Slider iiifContent="/api/facet/subject/war-pensions.json" />

Read more about creating custom content in the Create Markdown Content Guide.

Example War Pensions Content

Stackblitz Playground