internet archive recipes documented

Author: evanwill

docs/metadata/object-paths.md

@@ -15,6 +15,7 @@ This section presents example recipes for figuring out the fields for a few comm
 - [Self-Hosted Objects](#example-paths-for-external-or-self-hosted-objects)
 - [YouTube Objects](#path-for-youtube-objects)
 - [Vimeo Objects](#path-for-vimeo-objects)
+- [Internet Archive Objects](#path-for-internet-archive-objects)
 - [CONTENTdm Objects](#path-for-contentdm-objects)
 
 ------
@@ -98,6 +99,63 @@ One option is to create screenshots to use as derivative images--if image_thumb
 
 ------
 
+## Path for Internet Archive Objects
+
+[Internet Archive](https://archive.org/) image items are accessible via standard IIIF api.
+Check the [IA IIIF documentation](https://iiif.archive.org/iiif/documentation) for full details.
+This works well for adding image and book items into a CB collection without needing to store any objects in your project.
+You can upload your items at IA or curate existing items in for your exhibit.
+
+### Single Image Items
+
+For single image items following the standard CB set up, you will use the IIIF recipes to create image URLs for your "object_location", "image_small", and "image_thumb" fields. 
+To use the recipes you will need the image identifier--this is a bit tricky because you will need the item id plus the individual filename to create the identifier for IIIF.
+
+- **ID:** IA item id is the last part of the item's URL. 
+    - e.g. https://archive.org/details/mma_wheat_field_with_cypresses_436535 the id is `mma_wheat_field_with_cypresses_436535`
+- **Filename:** The filename can be found by checking the "Download Options" box on the item's page. Click "Show all" option. This will list various files. Look for the main JPG, which might have a strange name. 
+    - e.g. https://archive.org/download/mma_wheat_field_with_cypresses_436535 the filename is "436535.jpg".
+    - You can use this method to reference individual images from a book / multiple image items. Looking at the download files, the images will be in a zip folder (generally look for the JP2 version). You will separate each level of folders shown in the downloads by an escaped slash `%2f`. E.g. to get the cover of this [book item](https://archive.org/details/aladoren00newbuoft), the filename is `%2faladoren00newbuoft_jp2.zip%2faladoren00newbuoft_jp2%2faladoren00newbuoft_0001.jp2` (a zip file, then a folder, then the filename). Generally, it will be easier to get this info from the manifest.json!
+    - *Alternatively,* you can find the IIIF identifier by checking the "info.json" for an item following the pattern `https://iiif.archive.org/iiif/` + item id + `/info.json`, e.g. https://iiif.archive.org/iiif/mma_wheat_field_with_cypresses_436535/info.json. This json will have a field "@id" listed, with the full identifier following the "https://iiif.archive.org/image/iiif/2/" url. Note, "info.json" is only available for single image items!
+- **Identifier:** The identifier for IIIF will be the ID and Filename separated by an escaped slash `%2f` 
+    - e.g. `mma_wheat_field_with_cypresses_436535%2f436535.jpg`
+
+Once you have the identifier, you can use standard IIIF recipes to create urls that will retrieve appropriately sized images:
+
+- "object_location" = full sized, `https://iiif.archive.org/image/iiif/3/` + identifier + `/full/max/0/default.jpg`
+    - e.g. https://iiif.archive.org/image/iiif/3/mma_wheat_field_with_cypresses_436535%2f436535.jpg/full/max/0/default.jpg
+- "image_small" = 800px width, `https://iiif.archive.org/image/iiif/3/` + identifier + ``/full/,800/0/default.jpg`
+    - e.g. https://iiif.archive.org/image/iiif/3/mma_wheat_field_with_cypresses_436535%2f436535.jpg/full/,800/0/default.jpg
+- "image_thumb" = 450px width, `https://iiif.archive.org/image/iiif/3/` + identifier + `/full/,450/0/default.jpg`
+    - e.g. https://iiif.archive.org/image/iiif/3/mma_wheat_field_with_cypresses_436535%2f436535.jpg/full/,450/0/default.jpg
+
+### Book, Multiple Image Items, or IIIF Viewer
+
+To display an IA item with a IIIF viewer (instead of the default CB simple image style template), it is possible to use the "manifest.json".
+The full url to the "manifest.json" file will be used in the "object_location" field. 
+The recipe follows the pattern: 
+`https://iiif.archive.org/iiif/3/` + item id + `/manifest.json`
+
+e.g. for book item page, https://archive.org/details/aladoren00newbuoft
+the IIIF manifest will be at 
+https://iiif.archive.org/iiif/3/aladoren00newbuoft/manifest.json
+
+The recipe for manifest url is the same for both book and single image items, and can be used for either in the universal IIIF viewer. 
+You will still want to figure out appropriate derivatives for "image_small" and "image_thumb" using the recipes above or manually created images.
+
+With the manifest.json url in "object_location", you will then modify the "image" display_template or create a new display_template for the IIIF viewer items. 
+
+In "_layouts/item/image.html" (or a new file such as "_layouts/item/iiif_image.html") change
+`{% include item/image-gallery.html %}`
+to
+`{% include item/iiif-manifest-universal-viewer.html %}`
+
+Note: Universal Viewer this will work with manifest.json loaded from IA.
+However, for many other servers, attempting to load a remote manifest this will trigger a CORS issue.
+A potential work around is to download a the manifests and put them directly in your project to avoid CORS.
+
+------
+
 ## Path for CONTENTdm Objects
 
 The CONTENTdm API can be used to retrieve display images and file downloads from any CONTENTdm repository.