Nocturnal Prancing Mosquito

    embedza

    4.0.1 • Public • Published

    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

    Install

    npm i embedza

    DownloadsWeekly Downloads

    329

    Version

    4.0.1

    License

    MIT

    Unpacked Size

    77.6 kB

    Total Files

    32

    Last publish

    Collaborators

    • vitaly