Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.
JavaScript CSS HTML
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
config
docs
lib
support
test
.eslintignore
.eslintrc
.eslintrc.yml
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
index.js
package.json

README.md

embedza

Build Status NPM version Coverage Status

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, callback) and .set(key, value, callback) 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 [, callback]) -> 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 [, callback]) -> 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, 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:

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