# Inherits from: apostrophe-module
The oembed module provides an oembed query service for embedding
third-party website content, such as YouTube videos. The service includes
enhancements and substitutes for several services that do not support
oembed or do not support it well, and it is possible to add more by
enhanceOembetter method. The server-side
code provides a query route with caching. The browser-side code
provides methods to make a query, and also to make a query and then immediately
display the result.
Sites to be embedded need to be added to the
safeList, to avoid XSS attacks. Many
widely trusted sites are already on the list. This is troue even when
falling back to Open Graph, because of port scanning risks.
safeList option is concatenated with
list, plus wufoo.com, infogr.am, and slideshare.net.
The option name
allowlist is also permitted for consistency with oembetter
and other tools.
endpoints option is concatenated with
# query(req, url, options, mainCallback) [api]
This method fetches the specified URL, determines its best embedded
oembetter, and on success invokes its callback with null
and an object containing the oembed API response from the service provider.
oembetter has no luck, open graph is used as a fallback,
options.neverOpenGraph is set.
options.alwaysIframe is true, the result is a simple
iframe of the URL. If
options.iframeHeight is set, the iframe
has that height in pixels, otherwise it is left to CSS.
options object is passed on to
Responses are automatically cached, by default for one hour. See the cacheLifetime option to the module.
# openGraph(req, url, callback) [api]
Given a URL, return a nice oembed response for it
based on its Open Graph tags, or the best we can
fake, based on the HTML markup of the page. Called
for you by
oembetter is unsuccessful.
# iframe(req, url, options, callback) [api]
Given a URL, return an oembed response for it which just iframes the URL given. Fetches the page first to get the title property.
If options.iframeHeight is set, use that # of pixels, otherwise do not specify & let CSS do it.
self.query if the
# afterScriptLoads(script, beforeId, scriptId, then) [api]
cross-domain js file dynamically and then run
then string argument.
script should be a URL pointing to the third-party
js file and may start with // to autoselect
http or https depending on how the page was loaded.
You may supply an id attribute for the script tag. Some services rely on these (infogr.am).
You may also supply the ID of an element that the script should be inserted immediately before. Some services try to infer how they should behave from the context the script tag is in (infogr.am).
This code was inspired by the wufoo embed code and
is used to dynamically load wufoo and other services
that use js-based embed codes. See the oembetter
# pushAssets() [browser]
Push assets to the browser. Called by
# pushCreateSingleton() [browser]
Create the browser-side
apos.oembed singleton, enabling
Create the browser-side object
apos.oembed for convenient oembed queries
and display of oembed responses. Called by
Creates an instance of the
oembetter module and adds the standard allowlist.
Enhances oembetter to support services better or to support services
that have no oembed support by default. Called by
Extend this method to add additional
Add oembed query API routes. Called by
# API Routes
# GET /modules/apostrophe-oembed/query
Simple API to self.query, with caching. Accepts url and alwaysIframe parameters; alwaysIframe is assumed false if not provided. The response is a JSON object as returned by apos.oembed.