index.qmd

---
title: "Workshop: Building a Digital Exhibit"
subtitle: "From Archives to the Web in 60 Minutes"
lightbox: true
---

This tutorial will guide you through the process of publishing a digital exhibit using [CollectionBuilder](https://collectionbuilder.github.io/), a popular tool designed and maintained by librarians at the [University of Idaho](https://www.lib.uidaho.edu/).

To achieve this, we will be using three main tools:

::: {.grid}

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}
::: {.card}
::: {.card-body .d-flex .flex-column}
<div class="text-center" style="font-size: 3rem; color: #003660;">
{{< fa table >}}
</div>
<p class="card-title-p text-center">Google Sheets</p>
<p class="mt-auto align-self-center"><a href="https://docs.google.com/spreadsheets/d/1XUaY0MpVYpBd0QMcF96Vtx-e3Lue_a2TVkHGX7f57i8/edit?usp=sharing" class="btn btn-primary" target="_blank">Start Learning</a></p>
:::
:::
:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}
::: {.card}
::: {.card-body .d-flex .flex-column}
<div class="text-center" style="font-size: 3rem; color: #003660;">
{{< fa brands github >}}
</div>
<p class="card-title-p text-center">GitHub</p>
<p class="mt-auto align-self-center"><a href="https://github.com/" class="btn btn-primary"  target="_blank">Explore</a></p>
:::
:::
:::

::: {.g-col-12 .g-col-md-6 .g-col-lg-4}
::: {.card}
::: {.card-body .d-flex .flex-column}
<div class="text-center" style="font-size: 3rem; color: #003660;">
<i class="bi bi-braces-asterisk"></i>
</div>
<p class="card-title-p text-center">CollectionBuilder</p>
<p class="mt-auto align-self-center"><a href="https://collectionbuilder.github.io/" class="btn btn-primary"  target="_blank">Get Started</a></p>
:::
:::
:::

:::
---

## Prerequisites

To follow along with this tutorial, you will need:

- Access to your UCSB Google account to use Google Sheets.
- A GitHub account to manage your CollectionBuilder project.

::: {.callout-warning}
# 

If you don't have a GitHub account, go to [GitHub's Sign-Up Page](https://github.com/signup) and create one using your UCSB or any Google account. It's free and only takes a few minutes!
:::

## Step 1: Collect your materials

You can start by gathering some materials for your digital exhibit. For this tutorial, we will be using a small collection of vintage postcards from a private collection. These postcards feature various landmarks and scenes from around the world, and they will serve as the primary content for our exhibit.

To get started, download the images for this tutorial from [postcards.zip](objects/postcards.zip). Unzip the file and save the images to a folder on your computer where you can easily access them later.

## Step 2: Copy the Google Sheets template

- You can use this template to start creating your metadata: [CollectionBuilder Metadata Template](https://docs.google.com/spreadsheets/d/1XUaY0MpVYpBd0QMcF96Vtx-e3Lue_a2TVkHGX7f57i8/edit?usp=sharing).
- Make a copy of the template by clicking on `File` > `Make a copy` in the Google Sheets menu. This will create a new spreadsheet in your Google Drive that you can edit and customize for your exhibit.

## Step 3: Fill in the metadata

- Create the metadata for your exhibit by filling in the Google Sheets template. Each row in the spreadsheet represents an item in your collection, and each column corresponds to a specific metadata field. Some of the key columns you will need to fill out include:

| Column Name | Description |
|-------------|-------------|
| `objectid` | A unique identifier for each item (e.g., `postcard1`, `postcard2`). |
| `format` | [MIME Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) format of the object; e.g., 'image/jpg', 'image/png', 'application/pdf' |
| `filename` | The name of the file associated with the item (e.g., `postcard1.jpg`). |
| `title` | The title of the item (e.g., `Eiffel Tower Postcard`). |
| `description` | A brief description of the item (e.g., `A vintage postcard featuring the Eiffel Tower in Paris, France.`). |
| `date` | The date associated with the item (e.g., `1920s`). |
| `subject` | A list of keywords or subjects related to the item, separated by semicolons (e.g., `landmark; Paris; vintage`). |
| `location` | The location associated with the item (e.g., `Paris, France`). |
| `latitude` | The latitude coordinate of the item's location (e.g., `48.8584`). |
| `longitude` | The longitude coordinate of the item's location (e.g., `2.2945`). |
| `language` | The language of the item's description (e.g., `en`). |

Not all fields are mandatory, but we recommend filling out as many as possible to enhance the discoverability and richness of your exhibit. The `objectid`, `format`, and `filename` fields are essential for linking your metadata to the corresponding media files.

::: {.callout-warning}
# Save your metadata

CollectionBuilder requires that you save your Google Sheets metadata as a CSV file. To do this, go to `File` > `Download` > `Comma-separated values (.csv, current sheet)` in the Google Sheets menu. Save the CSV file to a location on your computer and name it as `metadata.csv`.

Don't open the CSV file in Excel or any other spreadsheet software, as this can alter the formatting and cause issues when uploading to CollectionBuilder.
:::

## Step 4: Use CollectionBuilder template to create a repository on GitHub

- Go to [CollectionBuilder website](https://collectionbuilder.github.io/) and choose the "GitHub Pages" template:

![CollectionBuilder GitHub Pages Templates](_static/templates.png)

![Go to GitHub Pages template](_static/gotoTemplate.png){width="400"}

- Create a new repository by clicking on the "Use this template" button. Then, select "Create a new repository":

![Create a new repository](_static/createRepo.png)

- Fill in the repository name (e.g., `postcard-exhibit`) and add a short description for the repository (e.g., `A digital exhibit showcasing vintage postcards from around the world.`). Make sure to set the repository to "Public". 
- Click on "Create repository" to start creating the repository.

![Create repository form](_static/createRepository.png){width="600"}

It's going to take a few seconds...

## Step 5: Upload your media files to GitHub

- Type `.` in the root of your repository to launch a web-based code editor. 

![Open GitHub code editor](_static/vscode_permit.png)

![Grant permission to open code editor](_static/vscode_grantpermit.png){width="600"}

![GitHub code editor](_static/vscode.png)

- Delete the existing media files in the `objects` folder (do not remove the `README.md` file):

![Delete existing media files](_static/deleteMedia.png){width="400"}

- Right-click on the `objects` folder and select "Upload":

![Upload media files](_static/uploadMedia.png){width="400"}

![Select media files](_static/selectMedia.png){width="400"}

![Upload media files to GitHub](_static/uploadMedia2.png){width="600"}

## Step 6: Upload your metadata CSV file to `_data` folder

- Upload your `metadata.csv` file to the `_data` folder:

![Upload metadata CSV file](_static/uploadMetadata.png){width="400"}

- Add and commit your changes to the repository:

![Stage changes](_static/satageChanges.png){width="400"}

![Add a commit message](_static/commitMessage.png){width="400"}

![Commit changes](_static/commitChanges.png){width="400"}

## Step 7: Configure CollectionBuilder

- Go to `_config.yml` file in the root of your repository and edit the following lines:

```yaml
##########
# SITE SETTINGS
#
# title of site appears in banner
title: Frankfurt Postcards
# tagline, a short phrase that will appear throughout the site in the top banner
tagline: a small exhibit of vintage postcards
# description appears in meta tags and other locations
# this description might appear in search result lists, keep around 160 characters max
description: "A digital exhibit showcasing vintage postcards from around the world."
# creator of the digital collection, to appear in meta tags; we typically use our GitHub usernames but feel free to just use your name
author: Jairo Melo

##########
# COLLECTION SETTINGS
#
# Change the file name from 'demo-metadata' to 'metadata' (without the .csv extension)
metadata: metadata
```

- Stage, commit, and push your changes to GitHub to update the repository.

## Step 8: Publish your exhibit

- Go to the "Settings" tab of your repository and scroll down to the "GitHub Pages" section. Under "Source", select the `main` branch and click "Save":

![GitHub Pages settings](_static/githubPages.png){width="600"}

- After a few moments, your exhibit will be published and you can access it at the URL provided in the "GitHub Pages" section.

![Deploying exhibit](_static/deploying.png){width="400"}

![Exhibit URL](_static/exhibitURL.png){width="400"}

![Exhibit homepage](_static/exhibitHomepage.png){width="600"}

Congratulations! You have successfully published your digital exhibit using CollectionBuilder. Now, it's time for some customization.

## Step 9: Customize your exhibit

- Most of the customization options for CollectionBuilder are available in `_data/theme.yml` file. Let's change some of the default settings to make our exhibit more personalized.

```yaml
##########
# HOME PAGE
#
# featured image is used in home page banner and in meta markup to represent the collection
# use either an objectid (from an item in this collect), a relative location of an image in this repo (ex. /assets/img/feature.jpg), or a full url to an image elsewhere
featured-image: post_02 # WARNING: use the objectid, not the filename for this field

# Select a theme from https://bootswatch.com/ and add the name of the theme here. The default is "flatly".
bootswatch: spacelab

```

- More complex customizations, such as changing the layout of the item pages or adding new features, will require editing the HTML and CSS files in the repository. But for now, you can explore the various options available in the `_data/theme.yml` file to further customize the look and feel of your exhibit.