Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nodeca/embedza

Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.
https://github.com/nodeca/embedza

Last synced: about 1 month ago
JSON representation

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

Awesome Lists containing this project

README 

        
embedza

=======



[![Build Status](https://img.shields.io/travis/nodeca/embedza/master.svg?style=flat)](https://travis-ci.org/nodeca/embedza)

[![NPM version](https://img.shields.io/npm/v/embedza.svg?style=flat)](https://www.npmjs.org/package/embedza)

[![Coverage Status](https://coveralls.io/repos/github/nodeca/embedza/badge.svg?branch=master)](https://coveralls.io/github/nodeca/embedza?branch=master)



> 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**](https://embedza.herokuapp.com/)



Install

-------



```bash

npm install embedza --save

```



run dev server (with debug messages):



```bash

DEBUG=embedza:* npm start

```



Example

-------



Render player for youtube video:



```javascript

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](https://github.com/sindresorhus/got). 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](npmjs.com/packages/request). You can

override it. For example to force use cache only.



### Templates



Manage available templates:



```js

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](https://github.com/itteco/iframely)

- [onebox](https://github.com/discourse/onebox)



Embedza is inspired by projects above, but designed to satisfy our requirements.

For example, it supports inline output format.



License

-------



[MIT](https://raw.github.com/nodeca/embedza/master/LICENSE)