SUL-Embed
An oEmbed provider for embedding resources from the Stanford University Library.
Development/Test Sandbox
There is an embedded static page available at /pages/sandbox
in your development and test environments. Make sure that you use the same host on the service input (first text field) as you are accessing the site from (e.g. localhost or 127.0.0.1).
To bring up a dev environment first you'll need to install Ruby and JavaScript dependencies. Note: NodeJS v14 and yarn must be installed:
bundle install
yarn install
Then start up the Rails app in one terminal window:
bin/dev
Then start the NodeJS process to make the JavaScript assets available:
bin/webpacker-dev-server
Now visit this URL in your browser!
http://localhost:3000/pages/sandbox
Webpacker in Docker
You may also use the provided docker container to run the webpacker dev server.
docker compose up webpacker
oEmbed specification details
URL scheme: https://purl.stanford.edu/*
API endpoint: https://embed.stanford.edu
Example: https://embed.stanford.edu/embed.json?url=http://purl.stanford.edu/zw200wd8767
Creating Viewers
You can create a viewer by implementing a class with a pretty simple API.
The viewer class will be instantiated with an Embed::Request object. The initialize
method is included in the CommonViewer
parent class but can be overridden.
module Embed
class Viewer
class DemoViewer < CommonViewer
end
end
end
The class must define a class method returning an array of which types it will support. These types are derived from the type attribute from the contentMetadata.
module Embed
class Viewer
class DemoViewer < CommonViewer
def self.supported_types
[:demo_type]
end
end
end
end
The file that the class is defined in (or your preferred method) should register itself as a view with the Embed module.
module Embed
class Viewer
class DemoViewer < CommonViewer
def self.supported_types
[:demo_type]
end
end
end
end
Embed.register_viewer(Embed::Viewer::DemoViewer) if Embed.respond_to?(:register_viewer)
Linking in viewers
The rich HTML payload that is supplied via the oEmbed API is an iframe. This means that all consumers will be embedding an iframe into their page. Given this fact, generating links will require explicit targets if they are not intended to internally replace embed content. Given this, there are two patterns that can be used. For links intended to download files, a target="_blank"
can be used (effectively opening a new tab for the download which is immediately closed). When using target="_blank"
add rel="noopener noreferrer"
particularly when linking externally (although this should be reserved for linking to internal resources when possible). See this blog post for an explanation. Note: This does not apply to WebAuth links.
For links that are intended to navigate the users browser away from the current page (e.g. the links to Memento/GeoBlacklight/etc.) then target="_parent"
should be used to give the link the default browser behavior. More about link targets.
Console Example
$ viewer = Embed.registered_viewers.first
=> Embed::DemoViewer
$ request = Embed::Request.new({url: 'http://purl.stanford.edu/bb112fp0199'})
=> #<Embed::Request>
$ viewer.new(request)
=> # your viewer instance
Customizing the Embed Panel
Viewers can customize the embed panel. To do this, create a template in app/views/embed/embed-this
, to provide the HTML for the embed panel.
See File viewers for an example.
Adding a Download Panel
Viewers can add their own download panel. To do this, create a template in app/views/embed/download
, to provide the HTML for the download panel.
In order to enable the download panel you need to provide a method in your viewer class. This method lets the footer logic know that the viewer will provide a download panel and it should render the Download button.
def show_download?
true
end