README
Portable Holes is a set of client-side adapters for various embed codes. It aims to keep your article bodies clean while still allowing you to have rich embeds within them. It is the successor to Embeditor.
The library is ~153 kB minified and ~35 kB gzipped. It runs in both Node.js and the browser.
Prerequisites
Portable Holes expects a jQuery like interface. This may change in the future but, for now, you will need to have jQuery/Zepto/Cheerio available as either window.$
or global.$
, or be passed in directly as an option key.
Installation
Node.js
npm install -g portable-holes
Browser: You can use something that supports CommonJS requires like Browserify, Webpack, or Rollup (using a CommonJS plugin).
Alternatively, you can take dist/portable-holes.js
and use a script tag.
<script src="portable-holes.js"></script>
Usage
Standalone Script
You can use it as a script that you pass markup through stdin.
npm install -g portable-holes
echo "<somemarkup>" | portable-holes
Working Example:
echo "<a href='http://projects.scpr.org/firetracker/oembed?url=http://projects.scpr.org/firetracker/rim-fire/' data-maxheight='450' class='embed-placeholder' data-service='firetracker'>Rim Fire</a>" | portable-holes
If you want to keep the process active while passing in multiple pieces of HTML, you should include \x04
(EOT character) as a delimiter between your HTML documents. Normally, a newline character is used to delimit standard input, but it's likely that our HTML will contain newlines and it's a bit hazardous to strip them out. Better to use a character that's highly-unlikely to be in your HTML.
Node.js
Portable Holes works in Node.js. Because it was originally built for the browser in Rails apps, it expects a jQuery-like root object. This may change in the future. For Node.js use, I recommend using Cheerio which is a stripped-down version of jQuery for parsing documents, and Najax to shim jQuery.ajax()
.
Configuration can be stored both in ~/.portable-holes.yml
or ./.portable-holes.yml
(the current directory). The individual settings from the configuration in the current directory takes precedence over those in the user's home folder.
// node.js
const PortableHoles = require('portable-holes'),
cheerio = require('cheerio');
global.$ = cheerio.load('<somemarkup></somemarkup>');
$.ajax = require('najax');
const holes = new PortableHoles();
holes.swap();
Browser
It even works in the browser! Just include dist/portable-holes.js
in a script tag within your HTML page and in your JavaScript:
// browser
var PortableHoles = require('portable-holes');
var holes = new PortableHoles();
holes.swap();
Note that you must have jQuery initialized on your page for this to work.
The PortableHoles class has an complete event that you can listen to. This event gets fired when all the placeholders have been processed. This is mostly useful in the standalone script, but it's possible that these events can come in handy in other ways.
holes.on('complete', function(){
console.log('COMPLETE');
});
There is also a swap event that gets fired whenever an individual placeholder has been swapped.
So what's it really doing?
Portable Holes works by replacing A
tags with a specific class with the
appropriate embed. The default class is embed-placeholder
, but that can be
configured.
There are several adapters included with this engine:
- Embedly - Covers several services, such as SoundCloud, Spotify, Scribd, Google Maps, and others. See the list of Embedly's providers. Embedly doesn't always work perfectly, so Portable Holes provides manual adapters for some of the providers that Embedly claims to support.
- Cover It Live
- Polldaddy
- KPCC's Fire Tracker
- Storify
- Brightcove
- Document Cloud
- Rebel Mouse
Configuration
PortableHoles
You can configure:
defaultAdapter
- The adapter that will be used if no adapter is found for the provided service.defaultService
- The service that will be used if no service is provided on the placeholder link.wrapperClass
- The class of the div that will get wrapped around the embed.placeholderClass
- The class of the<A>
tags that Portable Holes will look for.
Embeds
PortableHoles offers a system of configuration precedence. The order of precedence is:
data-attributes
on the placeholder link itself.- Adapter-specific configuration in the
PortableHoles
base object. - Global configuration on
PortableHoles
- Adapter-specific defaults.
data-attributes
You may add a data-attribute
to any placeholder link, which will be used
in the query or embed code. This method of specifying configuration takes
precedence over any other configuration. The names of the data-attributes
get passed directly to the query or embed code (depending on the adapter).
Only the data-attributes which have to do with the embed will be passed through;
attributes like data-service
won't be used.
In the following example, the maxheight
property will be sent to the oembed
endpoint:
<a href="http://projects.scpr.org/firetracker/oembed?url=http://projects.scpr.org/firetracker/rim-fire/" data-maxheight="450" class="embed-placeholder" data-service="firetracker">Rim Fire</a>
Adapter-specific configuration
When initializing the global PortableHoles
class, you may specify
configuration for individual adapters.
The display
object is for configuring display options. Properties:
placement
- the method to use for placing the embed, such asbefore
,after
, orreplace
. Default isafter
.
The query
object is for configuring the query parameters, or in the case of
an adapter which doesn't use a query, it's for configuring the embed properties.
For the most part, everything will be pretty consistent.
new PortableHoles({
Embedly: {
query: {
maxheight: 450
}
},
FireTracker: {
query: {
maxheight: 350
},
display: {
placement: 'replaceWith'
}
},
CoverItLive: {
query: {
maxheight: 500
}
}
})
Global configuration
You may also specify global configuration in PortableHoles
, which will be
used for all adapters:
new PortableHoles({
maxheight: 450,
maxwidth: 200
})
There are also some PortableHoles options you can configure:
$
- A specific jQuery-compatible API to use for DOM manipulation.defaultAdapter
- Adapter that gets used when the service isn't recognized. default:Embedly
defaultServer
- Service that gets used when thedata-service
attribute is missing. default:other
placeholderClass
- The class that the embed placeholders are given. default:embed-placeholder
wrapperClass
- The class the embed's wrapper is given. default:embed-wrapper
wrapperElement
- The element which should be wrapped around all embeds. default:div
defaultPlacement
- Default embed placement, if a placement is somehow missing or it doesn't exist in the PlacementFunctions object. default:after
Embedly
Embedly requires an API key.
You can provide it in the query
options for the Embedly adapter when
initializing PortableHoles
:
new PortableHoles({
Embedly: {
query: {
key: 'YOUR_API_KEY'
}
}
})
oEmbed vs. non-oEmbed
This library isn't necessarily tied to oEmbed, however it does have support for it. Even for services which support oEmbed, there are static templates which are able to render the embed properly just based off of the provided URL. This eliminates any oEmbed headaches (Access-Control-Allowed-Origin, for example), and also reduces the time it takes for an embed to load.
CKEditor plugin
An unofficial CKEditor plugin can be found HERE. Copy and paste it into your own repository.
Known Issues
- Cover It Live and Facebook embeds don't currently work together on the same page, due to a javascript conflict between the two.
Contributing
If you have an adapter that you think would be useful for many, please open up a pull request.