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.

Install

npm install embedza --save

run dev server (with debug messages):

DEBUG=embedza:* npm start

Example

Render player for youtube video:

var embedza = require('embedza')();

embedza.render('https://www.youtube.com/watch?v=JrZSfMiVC88', 'block', function (err, html) {
  if (err) {
    throw err;
  }

  if (html) {
    console.log(html);
  }
});

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, callback) and .set(key, value, callback) methods. Default stub does nothing.

.render(url, type, callback)

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')
• callback (Function) - function (err, result)
  • result.html - html code
  • result.type - matched format type

.info(url, callback)

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

• url (String) - resource URL.
• callback (Function) - function (err, result), result is:
  • 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

.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, function (env, callback).

.addMixin(options)

Add mixin (data handler). Options:

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

.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, function (env, callback).

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:

var _ = require('lodash');
var embedza = require('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