embedza

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.

Live Demo

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

• iframely
• onebox

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

License

MIT