Skip to content

nodeca/embedza

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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) -> 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

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published