# Panel Truck
panel-truck is a web UI tool for creating interactive storylines using images and maps. It's especially useful for libraries and museums that want to create linear narrations on top of one or multiple deep-zoomable objects. Panel-truck supports IIIF, static images, and tiled web map layers as sources. It is trivial to embed into an existing web site, and requires only a simple JSON file to construct a presentation.
WARNING
panel-truck 0.2 was released on 2021-02-12, introducing breaking changes to the format of the screenplay document. The hosted version of panel-truck 0.1 is still available at https://geoservices.leventhalmap.org/panel-truck/webcomponent-0.1/panel-truck.min.js
# Example
See an example panel-truck presentation that demonstrates some of its key features.
# Hosted Web Component
The simplest way is to embed panel-truck by importing it as a Web Component into an existing page.
- Import a Web Component polyfill if you plan to support older browsers that do not have native support for Web Components.
- Import Vue from a CDN or locally. If Vue is already part of your page's environment, you can omit this.
- Import the hosted panel-truck script from
https://geoservices.leventhalmap.org/panel-truck/webcomponent-0.2/panel-truck.min.js
- Create a sized container for the
panel-truck
component. It can be statically or dynamically sized; in either case, thepanel-truck
component will fill the size of its parent container. - Inside of your sized container, add the
panel-truck
component, and pass a JSON source for your screenplay, as<panel-truck screenplaySrc="https://some-example.org/screenplay.json"></panel-truck>
# Nutshell example
<!-- polyfill for Web Components; you can omit if you don't want to support older browsers -->
<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
<!-- you can omit the Vue import if Vue is already present -->
<script src="https://cdn.jsdelivr.net/npm/vue@2.6.12"></script>
<script src="https://geoservices.leventhalmap.org/panel-truck/webcomponent-0.2/panel-truck.min.js"></script>
<div style="width:1000px;height:800px;"><!-- the panel-truck component will take the size of its parent element -->
<panel-truck screenplay-src="https://some-example.org/screenplay.json"></panel-truck>
</div>
# Creating a screenplay
A screenplay is a JSON file. You can host it anywhere, or generate it dynamically.
✴️ keys are required
metadata
: ✴️ an object with the following key-value pairs:
title
: ✴️ stringsubtitle
: stringauthor
: stringdatePublished
: string; no date formatting is applied
sources
: ✴️ an array of objects, each of which is a single visual source for a "scene" (i.e., "slide"). each source consists of the following key-value pairs:
id
: ✴️ string, must be unique amongst all source objects in the arraytype
: ✴️ string, one of:iiifManifest
iiifImage
staticImage
geoMap
- If
type
isiiifManifest
, the additional key-value pairs:manifest
: fully qualified URL to a IIIF Manifestsequence
: defaults to0
if unsetcanvas
: defaults to0
if unsetimage
: defaults to0
if unset
- If
type
isiiifImage
:imageEndpoint
: fully qualified URL to Image endpoint
- If
type
isstaticImage
:imageFile
: a static image URL as a string
- If
type
isgeoMap
, one of the following key-value pairs:tileJSON
: a TileJSON URL as a stringtileXYZ
: an XYZ tile scema as a string, which must contain{x}
,{y}
, and{z}
placeholders- If neither
tileJSON
nortileXYZ
is set, the map loaded will be a default OSM map
moreInfo
: An optional URL to a page with more information about the object, such as a repository record page; this can also be overriden at the scene level by including amoreInfo
key in a scene object
scenes
: ✴️ an array of objects, each of which create a "scenes" (i.e., "slide") in the narration. Each scene object includes the following key-value pairs:
sceneSource
: ✴️ a string which must match theid
field of ONE entry in thesources
array.caption
: ✴️ an object with the following key-value pairs:title
: stringtext
: ✴️ string, accepts Markdown formatting
extent
: an array setting the extent of the image to be zoomed to fit the viewport, with the format[minX,minY,maxX,maxY]
. Ifextent
is unset, the scene will default to fit the entire image, or, in the case of ageoMap
, the entire world. You can also specify"extent": "fit"
to make this explicit.moreInfo
: a URL to a page containing more information about the object, which will override themoreInfo
attribute of the source
# Example: a minimum viable screenplay, with one scene
{
"metadata": {
"title": "A single-scene screenplay"
},
"sources": [
{
"id": "1",
"type": "iiifImage",
"imageEndpoint": "https://iiif.digitalcommonwealth.org/iiif/2/commonwealth:x633fb18t"
}
],
"scenes": [
{
"source": "1",
"caption": {
"text": "This is a map made by John Speed"
}
}
]
}
# Example: a complicated screenplay with every source type
See this Gist for the screenplay used to create the example panel-truck presentation from the first section of this document.
# License
Panel-truck is released on the MIT License. You can find the source code on GitHub. If you use it in a project and find it useful, you might:
- Let us know where you are using the project by sending us a note at info@leventhalmap.org
- Tag us on social media @bplmaps
- Retain the Leventhal Map & Education Center credit which is included by default in the final slide of a Panel Truck presentation
LMEC is a small nonprofit institution, financially independent of the Boston Public Library. If you have institutional resources available, consider making a donation to support our mission.