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: 7 months ago
JSON representation
Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags.
- Host: GitHub
- URL: https://github.com/nodeca/embedza
- Owner: nodeca
- License: mit
- Created: 2015-07-06T10:40:31.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-06-19T02:48:28.000Z (over 2 years ago)
- Last Synced: 2025-04-12T02:38:39.156Z (7 months ago)
- Language: JavaScript
- Homepage: https://embedza.herokuapp.com/
- Size: 934 KB
- Stars: 65
- Watchers: 8
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- stars - nodeca/embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. (JavaScript)
- awesome-nodejs - embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. (Packages / URL)
- awesome-node - embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. (Packages / URL)
- awesome-nodejs-cn - embedza - 使用oEmbed、Open Graph、meta标记中的信息从url创建HTML片段/嵌入 (目录 / URL)
- awesome-nodejs - embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. - ★ 37 (URL)
- awesome-nodejs-cn - embedza - 使用 oEmbed、Open Graph、meta 标记中的信息从 url 创建 HTML 片段/嵌入 (包 / URL)
- awesome-nodejs-cn - embedza - **star:65** 使用来自oEmbed, Open Graph, meta标签的信息从url创建HTML片段/嵌入 (包 / URL)
- fucking-awesome-nodejs - embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. (Packages / URL)
- fucking-awesome-nodejs - embedza - Create HTML snippets/embeds from URLs using info from oEmbed, Open Graph, meta tags. (Packages / URL)
README
embedza
=======
[](https://travis-ci.org/nodeca/embedza)
[](https://www.npmjs.org/package/embedza)
[](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)