=" Help & Workflows - IIIF Gallery Builder

📖 Help & Workflows

Learn how to build, save, and share your IIIF image galleries

Contents

🚀 Getting Started

What is this app?

The IIIF Image Gallery Builder helps you create custom collections of images from IIIF (International Image Interoperability Framework) manifests. You can:

Adding Images to Your Gallery

  1. Find a IIIF manifest URL from a participating institution
  2. Paste the URL into the "Add IIIF Manifest URLs" field
  3. Click "Add Manifest(s)"
  4. If the manifest contains multiple pages, you'll be able to select which ones to add
  5. Images appear as cards in the gallery
💡 Tip: View a list of participating institutions and instructions on how to locate manifests.

Viewing Images

Click any thumbnail to view the full high-resolution image in the OpenSeadragon viewer on the right. You can:

Organizing Your Gallery

💾 Saving & Loading Galleries

Saving to Your Computer

  1. Enter a name for your gallery in the "Gallery name" field
  2. Click "Save Locally"
  3. A JSON file will download to your computer
  4. Keep this file to reload your gallery later
💡 Tip: If you don't enter a name, the app will auto-generate one using today's date (e.g., "iiif-gallery-2025-01-15.json").

Loading a Saved Gallery

From a local file:

  1. Click "Choose File"
  2. Select your saved JSON file
  3. Click "Load File"
  4. Your gallery appears with all items in their saved order

From a URL:

  1. Paste the gallery JSON URL into the "Paste gallery URL" field
  2. Click "Load from URL"
  3. The gallery loads directly from the web
💡 Tip: You will learn to create shareable URLs for collections using GitHub Gist in the steps below!

🔐 Creating a GitHub Gist Account

GitHub Gist is a free service for hosting and sharing files. Creating an account allows you to:

Step-by-Step Account Creation

  1. Go to github.com/signup
  2. Enter your email address
  3. Create a password (at least 15 characters or 8 with a number and lowercase letter)
  4. Choose a username (this will be in your gist URLs)
  5. Verify you're not a robot (puzzle or email verification)
  6. Click "Create account"
  7. Verify your email address (check your inbox)
💡 Tip: GitHub accounts are free forever for public gists. You never need to upgrade to a paid plan for this use case.

Anonymous Gists (No Account Needed)

You can also create gists without an account, but:

⚠️ Important: Anonymous gists are permanent and cannot be edited or deleted. Always keep a local backup of your JSON file!

🔗 Sharing Your Galleries

Send someone your JSON file via email

  1. Save your gallery locally (download JSON file)
  2. Attach your JSON file to an email
  3. In the body of the email, paste the link to the webapp: https://davidrumseymapcenter.github.io/set-builder/
  4. Tell the recipient to download the file to their desktop and open it using the "Load Gallery" button in the app

Create a Sharable Link with GitHub Gist

  1. Save your gallery locally (download JSON file)
  2. Go to gist.github.com
  3. Sign in (or skip for anonymous gist)
  4. Drag and drop your JSON file into the text box, OR paste the contents
  5. In "Filename including extension" field, give it a descriptive name (e.g., "colonial-maps.json")
  6. Optionally add a description
  7. Click "Create public gist" (or "Create secret gist" for unlisted)
  8. Click the "Raw" button in the top-right corner
  9. Copy the URL from your browser's address bar
  10. Create your shareable link:
    11. https://davidrumseymapcenter.github.io/set-builder/?file=PASTE_GIST_RAW_URL_HERE

    Example:

    https://davidrumseymapcenter.github.io/set-builder/?file=https://gist.githubusercontent.com/kristinallarsen/dd25a0e3fb0535d10d81b327a0d45454/raw/3b479ead4429474900b817bdfe0579d53cefa935/Ink%2520and%2520Empire

    What Recipients Can Do

    When someone opens your shared link:

    • ✅ They see your gallery exactly as you saved it
    • ✅ They can view all the images
    • ✅ They can add more images if they want
    • ✅ They can save their own modified version
    • ❌ They CANNOT change your original gallery
    💡 Tip: Think of shared galleries as templates. Anyone can open them, customize them, and save their own version!

🎓 Embedding Galleries in Canvas LMS

You can embed your IIIF galleries directly into Canvas course pages using iframes. This allows students to interact with the gallery without leaving Canvas.

Step 1: Get Your Gallery URL

  1. Create and save your gallery
  2. Upload it to GitHub Gist (see Sharing section)
  3. Create your gallery URL:
    https://davidrumseymapcenter.github.io/set-builder/?file=GIST_RAW_URL
  4. Copy this complete URL

Step 2: Embed in Canvas

Method A: Using the Rich Content Editor (Recommended)

  1. In Canvas, edit the page where you want to embed the gallery
  2. Click the </> (HTML Editor) button in the toolbar
  3. Paste this code where you want the gallery to appear:
<iframe src="YOUR_GALLERY_URL_HERE" width="100%" height="800" style="border: 1px solid #ccc; border-radius: 4px;" title="IIIF Image Gallery"> </iframe>
  1. Replace YOUR_GALLERY_URL_HERE with your actual gallery URL
  2. Click the </> button again to return to visual mode
  3. Click Save

Method B: Using Canvas Apps (if available)

  1. In Canvas page editor, click the Apps button
  2. Select "Redirect Tool" or "External URL" if available
  3. Paste your gallery URL
  4. Set dimensions (width: 100%, height: 800px recommended)

Recommended Settings

Setting Recommended Value Why
width 100% Responsive, fits all screen sizes
height 800 or 1000 Enough space to see gallery and viewer
style border: 1px solid #ccc Visual separation from page content
title Descriptive name Accessibility for screen readers

Complete Example

<h2>Assignment: Analyze Colonial Maps</h2> <p>Explore the gallery below and select 3 maps for your analysis essay.</p> <iframe src="https://davidrumseymapcenter.github.io/set-builder/?file=https://gist.githubusercontent.com/username/abc123/raw/colonial-maps.json" width="100%" height="1000" style="border: 1px solid #ccc; border-radius: 4px; margin: 1rem 0;" title="Colonial Maps Gallery for Analysis Assignment"> </iframe> <p><strong>Can't see the gallery above?</strong> <a href="https://davidrumseymapcenter.github.io/set-builder/?file=..." target="_blank"> Open in new window </a></p>
💡 Pro Tip: Always include a "Open in new window" link as a fallback in case the iframe doesn't load on some devices or browsers.

Troubleshooting Canvas Embeds

Problem: "This content cannot be displayed in a frame"

Problem: Gallery appears but is cut off

Problem: Gallery doesn't work on mobile

⚠️ Canvas Permissions: Check with your institution's Canvas admin before embedding external content. Some institutions have strict iframe policies for student privacy and security.

Teaching Workflow with Canvas

  1. Create your gallery with assignment images
  2. Save and upload to Gist
  3. Create Canvas page with embedded gallery
  4. Students interact with gallery directly in Canvas
  5. Students can open in new window to save their own version
  6. Students submit their customized gallery links via Canvas assignment
💡 Advanced: Create different galleries for different modules and embed them in corresponding Canvas pages. Students can compare across weeks by revisiting earlier embedded galleries.

🎯 Suggested Workflows

📚 For Teachers: Create Assignment Starter Galleries

  1. Build a gallery with required images for analysis
  2. Save locally as "Assignment-Name-Starter.json"
  3. Create a gist (logged in to your account)
  4. Share the gallery link with students via your LMS or syllabus
  5. Students open the link, add their research images, and save with their name
  6. Students submit their gist links to you for grading

Benefits: All students start with the same base images, you can see exactly what each student added.

🔬 For Researchers: Version Your Collections

  1. Create your initial gallery and save as "Project-v1.json"
  2. Create a gist and note "Initial collection - 15 items"
  3. As you find more items, add them and save as "Project-v2.json"
  4. Create new gists for each major version
  5. In your publications, reference specific versions by their gist URLs

Benefits: Permanent, citable, linkable versions. Readers can see exactly what you were looking at. Track evolution of your research.

👥 For Collaborators: Build on Each Other's Work

  1. Person A creates initial gallery "Colonial Trade Routes" (5 items)
  2. Person A saves locally as "Colonial-Trade-Routes-v1.json"
  3. Person A creates a gist and shares the link with the team
  4. Person B opens the shared link, reviews the 5 items
  5. Person B adds 3 more items from their research (now 8 total)
  6. Person B saves as "Colonial-Trade-Routes-v2-extended.json"
  7. Person B creates their own gist and shares the updated link back
  8. Person C opens Person B's link, adds 4 items (now 12 total)
  9. Person C saves as "Colonial-Trade-Routes-v3.json"
  10. Person C shares their version with the team
  11. Team reviews all three versions (v1, v2, v3) side-by-side by opening multiple tabs
  12. Team decides which items to keep for the final version
  13. Person D compiles the best items from all versions (15 items total)
  14. Right click on "View Manifest" link in each card to copy URLs
  15. Person D saves as "Colonial-Trade-Routes-FINAL.json"
  16. Person D creates gist and shares as the canonical team version

Benefits:

  • Clear version history (v1, v2, v3, FINAL)
  • Each person's contributions are visible in their version
  • Original never gets overwritten - always available for reference
  • Team can compare versions to see evolution of the collection
  • No conflicts - everyone works on their own copy
  • Final version represents consensus from all contributors

Pro tip: Add version numbers and contributor names to gallery names (e.g., "Project-v2-JohnEdits") to track who added what.

📚 Terminology Guide

Understanding these terms will help you use the app more effectively:

IIIF Terms

IIIF (International Image Interoperability Framework)
A set of open standards for delivering high-quality, attributed digital objects online at scale. Enables images from different institutions to work together.
Manifest
A JSON file that describes a digital object (book, map, photograph, etc.) and its structure. Contains metadata and links to images.
Canvas
In IIIF, a canvas represents a single view or page. A multi-page book has multiple canvases.
Image Service
The server that delivers the actual image data, allowing for zooming and dynamic sizing.

App-Specific Terms

Gallery
Your collection of images displayed as cards. This is what you see on screen and can customize.
Card
A single item in your gallery showing a thumbnail and metadata for one image.
Save Locally
Download your gallery as a JSON file to your computer. You control the file and can re-upload it anytime.
Share
Create a public link to your gallery by uploading it to a hosting service (like GitHub Gist).
Deep Link
A URL that automatically loads a specific gallery. Format: yourapp.com/?file=gallery-url
Fork
Opening someone else's gallery, modifying it, and saving your own version. The original remains unchanged.

GitHub Terms

Gist
A simple way to share files (like your gallery JSON) with others. Can be public or secret (unlisted).
Raw URL
The direct link to the file content (not the GitHub webpage). This is what you use in your deep links.
Anonymous Gist
A gist created without logging in. Cannot be edited or deleted once created.
Public Gist
Discoverable in search and your profile. Good for sharing widely.
Secret Gist
Not listed in search, but anyone with the link can access it. Good for limited sharing.

Compatibility & Known Limitations

Library of Congress Manifests

Due to the Library of Congress's security policy, manifests cannot be added directly from their website to the gallery. However, you can still use LOC items with a simple workaround.

Workaround for LOC Manifests:

  1. Visit the LOC manifest URL in your browser (e.g., https://www.loc.gov/item/74693169/manifest.json)
  2. The JSON data will display in your browser
  3. Copy all the JSON text (Ctrl+A or Cmd+A to select all, then Ctrl+C or Cmd+C to copy)
  4. Paste into a text editor and save as a .json file (e.g., loc-map.json)
  5. In the Gallery Builder, use the "Choose File" button under "Load Gallery" to upload your saved file
  6. The LOC items will appear in your gallery
  7. When you save your gallery, LOC items are preserved and will load normally in the future
Note: This workaround is only needed when first adding LOC items. Once saved in your gallery file, they work like any other manifest.

Getty Museum

Getty Museum manifests may display "No date returned" because Getty does not include creation dates in their IIIF metadata. This is a limitation of Getty's metadata, not the Gallery Builder. All other information (title, artist, collection) displays correctly.

Other Institutions

The Gallery Builder supports IIIF Presentation API 2.0 and 3.0 manifests from hundreds of institutions worldwide. If you encounter issues with a specific institution, please check that:

  • The URL is a valid IIIF manifest (should end with /manifest.json or /manifest)
  • The manifest is publicly accessible (not behind a login)
  • The institution supports CORS (cross-origin requests) for their IIIF content

🔧 Troubleshooting

Institutions have adopted IIIF in a variety of ways, and this is reflected in differences in manifests. The Gallery Builder may not recognize the structure of some manifests. We are committed to expanding compatibility! If you discover manifests that can not be ingested by this tool, please let us know by creating an issue in GitHub or emailing rumseymapcenter@stanford.edu.

Adding Manifests

Problem: "Error fetching IIIF Manifest"

Possible causes:

  • Invalid URL (typo or incomplete URL)
  • The server is down or slow
  • URL is not a IIIF manifest (might be a webpage instead)
  • CORS (Cross-Origin Resource Sharing) restrictions

Solutions:

  1. Double-check the URL is complete and correct
  2. Try opening the URL directly in a new browser tab - does it show JSON?
  3. Make sure it's a manifest URL (usually contains "/manifest" or ends in .json)
  4. Try again in a few minutes (server might be temporarily down)
  5. Try a different manifest to verify the app is working

Problem: Manifest loads but no images appear

Possible causes:

  • Manifest doesn't contain image data (might be collection-level manifest)
  • Images use an unsupported IIIF version
  • Image service URLs are broken

Solutions:

  1. Check browser console (F12) for error messages
  2. Verify the manifest URL is for a specific item, not a collection
  3. Try a known-working manifest to test

Viewing Images

Problem: Clicking thumbnail does nothing

Solutions:

  1. Make sure you're clicking the thumbnail image (not the card background)
  2. Check if the viewer panel is visible (might be resized too small)
  3. Try dragging the divider between gallery and viewer to make viewer larger
  4. Refresh the page and try again

Problem: Image loads but won't zoom

Solutions:

  1. Make sure your mouse is over the image viewer area
  2. Try using the +/- buttons instead of mouse wheel
  3. Some images might be low resolution and have limited zoom
  4. Check if browser zoom is interfering (reset to 100%)

Saving & Loading

Problem: "Failed to load manifest" when uploading JSON

Possible causes:

  • File is not valid JSON (corrupted or wrong format)
  • File was edited incorrectly
  • Wrong file selected

Solutions:

  1. Make sure you selected a .json file downloaded from this app
  2. Don't edit the JSON file manually unless you know JSON syntax
  3. Try opening the JSON file in a text editor - does it look like valid JSON?
  4. Re-download the original from your gist if you have one

Problem: Can't find my downloaded JSON file

Solutions:

  1. Check your browser's Downloads folder
  2. Look in your default download location (usually ~/Downloads or C:\Users\YourName\Downloads)
  3. Check browser's download history (Ctrl+J or Cmd+J)
  4. Re-export the gallery if you can't find it

Sharing & Gists

Problem: Deep link doesn't load the gallery

Solutions:

  1. Verify the URL format: yourapp.com/?file=GIST_RAW_URL
  2. Make sure you used the "Raw" gist URL (not the gist page URL)
  3. Check that the gist is public (not private)
  4. Try opening the gist raw URL directly - does it show JSON?
  5. URL encoding: make sure special characters are properly encoded

Problem: Gist was created but link doesn't work

Common mistake:

Using the gist page URL instead of the Raw URL.

Wrong: https://gist.github.com/username/abc123

Right: https://gist.githubusercontent.com/username/abc123/raw/filename.json

Always click the "Raw" button and use that URL!

Canvas LMS Embedding

Problem: "This content cannot be displayed in a frame"

Cause: Canvas security settings block external iframes.

Solutions:

  1. Contact your Canvas administrator to whitelist GitHub Pages
  2. Use "Open in new window" link instead of iframe
  3. Use Canvas "Redirect Tool" if available

Problem: Iframe shows but gallery is cut off

Solutions:

  1. Increase iframe height (try 1000 or 1200 instead of 800)
  2. Make sure width is set to 100% (not fixed pixels)
  3. Check that you didn't accidentally add CSS that limits height

General Issues

Problem: App is slow or unresponsive

Solutions:

  1. Some slowness can be expected since images are being retrieved from remote servers
  2. Close other browser tabs to free up memory
  3. Refresh the page
  4. Try a different browser

Problem: Layout looks broken on mobile

Solutions:

  1. Try rotating to landscape orientation
  2. The app works best on tablets and larger screens
  3. On small phones, use "Open in new window" for better experience

Still Having Issues?

If you're experiencing problems not covered here:

  1. Check the browser console for error messages (press F12, click Console tab)
  2. Try in a different browser (Chrome, Firefox, Safari, Edge)
  3. Clear browser cache and cookies
  4. Make sure you're using a modern, updated browser
  5. Check if your institution's firewall is blocking external resources
💡 For Developers: This is an open-source project. You can view the source code, report issues, or contribute improvements on GitHub.

Technical Notes

Overview

The IIIF Image Gallery Builder is a web-based tool that allows users to curate custom collections of images from any institution that provides IIIF-compliant image manifests. Users can select individual pages from multi-page documents, reorder items through drag-and-drop, and export their curated galleries in formats optimized for different use cases.

Why Two Export Options?

The application provides two distinct save/export formats, each serving a specific purpose:

1. "Save Gallery" (for reloading in this app)

File format: -gallery.json (Collection format with embedded manifests)

This option preserves your complete working state, including:

  • The exact selection of pages you chose from multi-page documents
  • The order you arranged items through drag-and-drop
  • The full metadata for each image
  • All manifest information needed to reload your gallery exactly as you left it

Technical detail: This format embeds complete IIIF manifests within a Collection structure. While this isn't how IIIF Collections typically work (they usually reference manifests by URL rather than embedding them), it's necessary because when you select specific pages from a 100-page book, that modified manifest doesn't exist anywhere on the web—it only exists in your browser session. By embedding the modified manifest, we preserve your exact curation choices.

Use case: You're building a gallery over multiple sessions, or collaborating with others who also use this tool.

2. "Export Manifest" (for IIIF viewers)

File format: -manifest.json (Flattened IIIF Presentation manifest)

This option creates a single, standards-compliant IIIF manifest that can be opened in any IIIF viewer (Universal Viewer, Mirador, etc.). All your selected images are combined into one sequence, with:

  • Proper canvas labels extracted from metadata
  • Source attribution preserved in metadata fields
  • Full IIIF 2.0 compliance for maximum compatibility

Technical detail: This format "flattens" all your selections into a single manifest with one sequence containing all canvases. It's completely portable and works in any IIIF-compatible viewer or application.

Use case: You want to share your curated gallery publicly, embed it in a website, or open it in professional IIIF viewing applications.

Key Design Decisions

Client-Side Architecture

The application runs entirely in the browser with no backend server. This means:

  • For users: No account creation, no data tracking, instant performance
  • For developers: No hosting costs, no server maintenance, easy deployment via GitHub Pages
  • Trade-off: Collections must embed manifests rather than reference them by URL (since there's nowhere to host the modified manifests we create)

Page Selection Feature

When users add a multi-page IIIF manifest (like a 200-page book), they can select only the specific pages they want. This creates a "modified manifest" that exists only in the application's memory. This modified manifest cannot be referenced by URL because it doesn't exist at a URL—it's ephemeral.

This is why the "Save Gallery" format embeds complete manifests: to preserve these user-curated selections. Without embedding, we would lose the user's page selections and have to include entire multi-page documents.

Standards Compliance

The application handles both IIIF Presentation API 2.0 and 3.0 manifests, and automatically sanitizes common validation issues found in source manifests (such as David Rumsey's otherContent field being a string instead of an array). The exported -manifest.json files are fully IIIF 2.0 compliant and pass validation.

Why Not Full IIIF Collection Compliance?

A standards-compliant IIIF Collection references manifests by URL rather than embedding them. For this app to create compliant collections, it would need to:

  1. Host each modified manifest at a unique URL
  2. Create a collection that references those URLs
  3. Maintain that hosting indefinitely

This would require either:

  • A backend server (eliminating the simplicity of client-side operation)
  • Integration with a third-party hosting service (adding complexity and dependencies)
  • A manual workflow where users host files themselves (poor user experience)

The current approach trades IIIF Collection compliance for:

  • Simplicity: No server, no hosting, no accounts
  • Functionality: Preserve page selections and custom ordering
  • Portability: The -manifest.json export provides full IIIF compliance for sharing

Use Case Scenarios

Researcher creating a teaching resource:

  1. Selects relevant pages from multiple archival collections
  2. Arranges them in pedagogical order
  3. Saves progress with "Save Gallery"
  4. When finished, uses "Export Manifest" to share with students via Universal Viewer

Digital Humanities project:

  1. Curates images from different institutions for a digital exhibition
  2. Collaborates with colleagues by sharing the -gallery.json file
  3. Exports final manifest for embedding in project website

Librarian building subject guides:

  1. Pulls relevant maps from various IIIF repositories
  2. Reorders them thematically through drag-and-drop
  3. Maintains working collection in -gallery.json format
  4. Publishes finished galleries as -manifest.json files for patrons

Technical Benefits

  • Zero infrastructure costs: Runs on GitHub Pages or any static host
  • Privacy-preserving: No user data collected or stored server-side
  • Extensible: Open source, easy to fork and modify
  • Format flexibility: Dual export system serves both internal and external use cases

Conclusion

The IIIF Image Gallery Builder's dual-export system reflects a pragmatic balance between user functionality and technical standards. The -gallery.json format prioritizes preserving user intent (page selections, ordering, working state) while the -manifest.json format prioritizes interoperability with the broader IIIF ecosystem. This approach delivers a powerful, simple-to-use curation tool without requiring server infrastructure, while still producing standards-compliant outputs for public sharing.