README

embedza

Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.

Key feature:

Supports both block & inline snippets (by default extracts data from oembed, opengraph and meta tags).
Light placeholders for video players to load page without delays. Iframes are loaded only after user clicks "play" button.
Cacheing.
Easy to customize and extend.
Dev server to test your changes.

Install

npm install embedza --save

run dev server (with debug messages):

DEBUG=embedza:* npm start

Example

Render player for youtube video:

const Embedza = require('embedza');
const embedza = new Embedza();

embedza.render('https://www.youtube.com/watch?v=JrZSfMiVC88', 'block')
  .then(result => {
    if (result) console.log(result.html, result.type);
  });
});

API

new Embedza(options)

Creates new Embedza instance with specified options:

enabledProviders - array of enabled providers or true for all providers, default true.
cache - object with .get(key) -> Promise and .set(key, value) -> Promise methods. Default stub does nothing.
request (optional) - any options for external requests, as described in got docs. For example, you can customize user agent header.

.render(url, type) -> Promise

Try to create HTML snippet of requested type by URL.

url (String|Object) - content url or result of .info().
type ([String]|String) - format name or list of suitable formats by priority ('block', 'inline')

Returns:

result.html - html code
result.type - matched format type

If url can not be rendered - returns null. On remote errors fails with error info.

.info(url) -> Promise

Similar to .render(), but returns object with full url description.

url (String) - resource URL.

Returns:

result.domain - domain plugin id ('youtube.com', 'vimeo.com', ...)
result.src - source url
result.meta - title, description, site
result.snippets - snippets data: type, tags, href, media, html

If url info does not exists - returns null. On remote errors fails with error info.

.forEach(fn(rule))

Iterates through domains rules to modify those.

.rule(name)

Get domain rule by name.

.addDomain(options)

Rerister new service. If String passed - enable domain with default rules. If Object passed - create custom configuration:

id (String) - provider ID (youtube.com)
match ([RegExp]|RegExp) - patterns to match
fetchers ([String|Function|Object]) - optional, array of fetchers dependency
mixins ([String|Function]) - optional, array of mixins dependency
mixinsAfter ([String|Function]) - optional, array of mixins after dependency
config (Object) - additional config: autoplay parameter name, API key

.addFetcher(options)

Add add data fetcher. Options:

id (String) - fetcher name.
priority (Number) - optional, run priority, default - 0.
fn (Function) - fetcher handler, async function (env).

.addMixin(options)

Add mixin (data handler). Options:

id (String) - mixin name.
fn (Function) - mixin handler, async function (env).

.addMixinAfter(options)

Add post-processor "after" handler. The same as .addMixin, but handlers are axecuted after all mixins. Options:

id (String) - post-processor name.
fn (Function) - post-processor handler, async function (env).

Advanced customization

.request()

By default it's a wrapper for request. You can override it. For example to force use cache only.

Templates

Manage available templates:

const _       = require('lodash');
const Embedza = require('embedza');
const embedza = new Embedza();

// Customize templates
embedza.templates['default_inline'] = _.template('...template code...', { variable: 'self' });
embedza.templates['youtube.com_player'] = _.template('...template code...', { variable: 'self' });

// Customize template aliases
embedza.aliases.block = [ 'player', 'photo' ];

Similar projects

Embedza is inspired by projects above, but designed to satisfy our requirements. For example, it supports inline output format.

License

MIT

Usage no npm install needed!