Wax
Create your own IIIF images for scholarly exhibits
Wax requires more technical skills than any other tool covered by this resource, but offers a unique and accessible means of learning the basics of web development, metadata creation and management, and plain text editing. Wax isn't a tool or platform so much as a workflow - that can make a configurable, static website with only a folder of images and a spreadsheet of image metadata.
Like CollectionBuilder, websites made with Wax (such as this demo) are free to set up and host using GitHub pages. They offer flexibility, freedom from ads and branding, and are particularly suitable for hosting high-quality image collections and scholarly exhibits.
Wax not only supports the display of pre-existing IIIF content, it allows its creation. While it’s possible to embed pre-existing IIIF objects in iframes, as on any other website, Wax can also create and serve your own IIIF-compliant images - without a server. Standard tifs and jpegs are added to the workflow, transformed into IIIF tiles, compiled into multi-page objects, and made accessible in an OpenSeaDragon viewer. This allows anyone to host a free website featuring IIIF content, with no underlying IIIF infrastructure or server access.
I set up a simple demo, starting with just six digital objects with their metadata. I used a couple of photos, poems, and multi-page letters from the Edward Thomas archive, held at Special Collections and Archives, Cardiff University.
The images used in the site can be filtered by any criteria you choose (in this example, I've set up category filters for photos, poems, or letters) via the homepage, or via the Browse page. The metadata attached to the images can be keyword-searched via the Search page. Results update responsively as keywords are entered.
An Exhibits collection stores sample pages featuring different ways of presenting illustrated narratives in markdown. Wax supports html iframes - allowing the inclusion of pre-existing IIIF content, as well as IIIF objects generated by Wax. In one example, exhibition text wraps around a Universal Viewer, embedded in an iframe, while another uses an inline parallax image - a jpeg tiled by Wax for IIIF delivery (scroll down to see the effect).
I've tested Wax with content generated by a student project on historic maps, to demonstrate how the platform can support various functionalities within the context of a full exhibition. Geographies of Power features images converted to IIIF by Wax itself, as well as three different kinds of embedded IIIF objects on one page - a map from Cardiff University's repository, another from Library of Congress, and an Exhibit combining maps from multiple sources.
Creating your metadata
Wax can work with CSV, JSON, and YAML metadata files, though CSV is recommended. Create your CSV in Google Sheets rather than Excel, which can cause encoding errors.
Every row in the spreadsheet will represent a digital object.
The only mandatory columns are pid and label.
Pid is the persistent identifier for each digital object. It must be unique. Use lowercase, don’t include spaces, and keep the identifiers simple, e.g. poem001.
Label is the title for each digital object. This should be a succinct description, as it will be displayed on your site, e.g. ‘The Ash Grove, 1916’.
You can add as many other descriptive metadata fields / spreadsheet columns as you like. Keep the field names in lowercase, avoid special characters, except underscores, which should be used rather than spaces. The field names only need to make sense to you - you can change how they will display on your site later.
Some field names will cause confusion with the underlying software of. Avoid id (use pid instead), date (use _date instead), and tags for category filtering (use object_type instead).
I used pid, label, author, description, and _date to describe each object, and object_type to add a category for filtering (see table below).
Export the metadata file in csv format, saving locally it with a simple name, e.g. metadata.csv
| pid | label | author | description | _date | object_type |
|---|---|---|---|---|---|
obj1 | The Ash Grove, 1916 | Edward Thomas | Manuscript, second draft… | 1916 | poem |
obj2 | Blenheim Oranges, 1916 | Edward Thomas | Manuscript draft in ink… | 1916 | poem |
obj3 | 17 Oct 1897 | Edward Thomas | Letter from… | 17 Oct 1897 | letter |
obj4 | 14 Nov 1897 | Edward Thomas | Letter from… | 14 Nov 1897 | letter |
obj5 | Turner’s Tower, Somerset, 1913 | Edward Thomas | Image of… | 1913 | photo |
obj6 | Alresford, Winchester, 1913 | Edward Thomas | Image of… | 1913 | photo |
Preparing your images
Wax accepts .tiff, .jpeg, .png, and .pdf files, and assumes relatively high resolution. For best results, resolution should be as standard as possible across the collection.
For Wax to work, each source image file must be named to exactly match the same pid used in the metadata.
Single image objects, such as obj1 in my example, must use the pid as its filename - e.g. obj1.jpg.
A multi-page object, such as obj3, must be stored in a folder named after the pid, e.g. obj3, and contain images named with a running file number, according to the order you want the images to appear, e.g. page 1 = 001.jpg, page2 = 002.jpg, etc.
Store all your images and any related folders in one single folder locally. Name it simply - mine was edward.
Setting up your system
Install a text editor if you don’t have one. Atom or Visual Studio Code are good options. You will also need GitHub Desktop.
Install Docker and Git. I originally attempted to install the five individual software components manually, but some of the instructions in the documentation are out of date. Installing Docker, where all of the required software is pre-bundled into one container, works without any issues.
Open your command prompt and check that Docker and Git are correctly installed:
Log into GitHub, or register a new account.
Go to the Wax repository and click Use this Template (green button) > Create a new repository.
This prompts you to create a copy of the repository, attached to your own account. You should name it after the collection or exhibition you’ll make, since this name will be displayed in your free URL for the project with GitHub. I called mine wax-demo.
Go to your new Wax repository page, click the green Code button, and copy the URL it provides to your clipboard. This should look like: https://github.com/[YOUR_GITHUB_USERNAME]/[YOUR_REPOSITORY_NAME].git
Open command prompt, and change directory into where you’d like to work on your project, e.g.
Run the git clone command plus the link you copied in one line, e.g.
Open Docker Desktop. I couldn’t work out where to go to build the image, but right-clicking on the Docker Desktop icon in the system tray, and launching Quick Start Guide worked for me. Click Start, and use the new terminal on the right to build the site.
First, change directory into your newly cloned project folder, which will be the same as your repository name, e.g.
Build the minicomp/wax base Docker image (don’t forget the “.” at the end!) You only need to do this once.
Every time you want to build a new Wax site, you can create and access an interactive bash container from the image by running:
Inside the container, update the dependencies by running:
Check that you have the wax_tasks available by running:
This will display a summary list of all the things Wax can do. Leave the terminal open while you add your collection data to the repository.
Open File Explorer, and navigate to your new Wax repository.
The repository contains sample data for an exhibition about Qatar, which helps you understand which files need to be stored where. Start by deleting this template data. Delete the _qatar folder. Open the img folder and delete the derivatives folder inside. Open the _data folder and delete the csv files. Then open the raw_images folder and delete the contents.
Next, add your top-level image folder and all of its contents, e.g. edward to the raw_images folder, then one level up, add your metadata.csv file to the _data folder.
At the top level of the repository, open the _config.yml file in your text editor. Update the title, description, copyright, url (e.g ‘https://[YOUR_GITHUB_USERNAME].github.io’) and baseurl (e.g. ‘/[YOUR_REPOSITORY_NAME]’) with your own details.
Further down the code, in COLLECTION SETTINGS, update all instances of qatar to the name of your image folder (e.g. edward). Check the collection name, layout, and raw_images path. Update metadata source to the name of your csv file. The template data looks like:
I changed mine to look like this:
In SEARCH INDEX SETTINGS, update the word qatar, and the list of fields to reflect the ones you’ve used. Only include fields you want to make searchable. Mine looks like:
Further down, you can configure the MENU and FOOTER for your site, but this can be done at any stage.
The layout edward_item, referred to in the COLLECTIONS code, didn’t exist, so I needed to create it. Go to _layouts, and open the qatar_item layout in a text editor. Rename it to [YOUR_IMAGE_FOLDER NAME]_item, and update the content related to labels and values. The values are the names of the field names you’ve chosen, and the labels the text that you want to display on your site. Mine looks like:
If you want to add links to your metadata, add type: link underneath the value.
Check the index.md file, and the contents of _pages, removing any references to qatar, and configuring as required.
Running the tasks - create IIIF images
Go back to Docker, and run:
When you run the line above for your collection, the task will:
Look for the directory of source images you specified in your _config.yml file under collections > [YOUR COLLECTION_NAME] > images > source.
Generate many IIIF derivatives, image tiles, and JSON representations of the collection items into the directory img/derivatives/iiif.
Automatically add three fields (full, thumbnail, and manifest) to each of your metadata records with the relative paths to the full and thumbnail size image derivatives and the IIIF manifest.
Running the tasks - create collection pages
In Docker, run:
This will:
Look for the metadata file you specified in your _config.yml file under collections > [YOUR_COLLECTION_NAME] > metadata > source.
Generate a directory named after your collection prepended with an underscore (e.g., _[YOUR_COLLECTION_NAME]).
Generate pages into that directory for each record, named after its pid value.
Running the tasks - create the search index
In Docker, run:
Your search name is the word found under ‘search’ in the SEARCH section of your config.yaml file, e.g. main
This will:
Look for the search configuration you set up in your _config.yml file.
For each collection you gave the search, it will look for the markdown pages, and add the fields and/or content from each page to the index.
It will write the index as a JSON file to the filename you gave (e.g. /search/index.json).
You’re now finished with Docker. You can exit by typing the command ‘exit’, which will destroy the container but not the base image. You can create and accessing a new container whenever you want to create a new Wax site by running the command below, updating the dependencies, and checking the tasks are available:
Configuration
Further configuration can be applied through the use of theme layouts and components.
Make your site live via GitHub Pages
So far, you’ve been working with files stored locally on your PC. In order to host your site online, you need to send copies of these files to GitHub.
Open GitHub Desktop, and click on New > Create a repository. Enter the name of your repository, and you will be be prompted to ‘add this repository’. Click this, and confirm. Enter ‘new site’ in the summary box, and commit to main. Finally, push commit to the origin remote. In a few minutes, your online files will match your local files. In GitHub, go to your repository’s ‘Action’ tab to see the workflow run live.
When completed, go to the Settings tab > Pages.
Under Source, select ‘deploy from a branch’ and set ‘branch’ to ‘main/(root)’, then click ‘save’.
Wait a few minutes for site to build. When you refresh the page, it should now say, ‘Your site is published at https://[YOUR_USERNAME].github.io/[YOUR_REPOSITORY_NAME]’. Congratulations - your site is live!
Last updated
