Install
$ npm install --save @vidy/embed
Then with a module bundler like rollup or webpack, use as you would anything else:
// using ES6 modules
import Vidy from '@vidy/embed';
import '@vidy/embed/dist/embed.css';
// using CommonJS modules
const Vidy = require('@vidy/embed');
require('@vidy/embed/dist/embed.css');You may also use the UMD build within a <script> tag if you'd prefer:
<script src="https://unpkg.com/@vidy/embed/dist/embed.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@vidy/embed/dist/embed.css">This registers the
Vidyconstructor globally.
Usage
Basic Setup
This assumes text content exists at time of instantiation.
import Vidy from '@vidy/embed';
import '@vidy/embed/dist/embed.css';
let vidy = new Vidy({
appid: '2199e8c8-abcd-efgh-a123-d463129790c5',
postid: 'hello-world',
content: '#article',
autoload: true
});Dynamic Setup — AKA, no autoload
When text is rendered dynamically / after script execution.
import Vidy from '@vidy/embed';
import '@vidy/embed/dist/embed.css';
let selector = '#article';
let div = document.querySelector(selector);
let pathname = location.pathname; //=> eg "hello-world"
let vidy = new Vidy({
appid: '2199e8c8-abcd-efgh-a123-d463129790c5',
postid: pathname,
content: selector
});
// Query our own Blog API for JSON
fetch(`/api/posts/${pathname}`).then(r => r.json()).then(data => {
// Add text to the container we care about!
div.innerHTML = data.html;
// Manually call load()
vidy.load();
});API
Vidy(options)
Returns: Vidy
Returns the Vidy instance.
options.appid
Type: String
Required: true
The Application identifier.
You may create a new Vidy Application for free here!
🎉
options.postid
Type: String|Number
Required: true
The unique identifier for any given page.
Most web frameworks have built-in helpers to generate & ensure unique page identifiers; see some examples for help. You may also resort to using the location.pathname, if necessary.
Important: This should be immutable; each
postidyields its own specific list of Vidy Embeds!
options.content
Type: String
Default: 'body'
The selector of the parent container that wraps the text content Vidy should traverse.
For example, given the following markup:
<body>
<div id="app">
<header id="top">
<nav>...</nav>
</header>
<div class="wrapper">
<main id="content">
<article>
<!-- content lives here -->
</article>
<div id="comments">...</div>
</main>
<aside id="sidebar">
<div id="trending-posts">...</div>
<div id="related-posts">...</div>
</aside>
</div>
</div>
</body>By default, the Vidy SDK will grab all text on the page, including comments, related & trending post widgets, etc. You probably don't want the SDK placing links in these areas.
Instead, you could pass content: '#content', targeting the article and the comments' text; or you can narrow link placements within the article exclusively via the '#content > article' selector.
options.autoload
Type: Boolean
Default: false
Whether or not the SDK should immediately draw link around text phrases.
If the text within options.content is loaded dynamically (eg, via an API or a headless CMS), then autoload should retain the false default.
Important: This should only be
trueif your content is included in the server response!
init(postid)
The method that appends the SDK elements to the page, if they don't already exist. It also queries the Vidy API for the list of Embeds (both social & advertising) that belong to the given postid.
If no postid is received, the SDK uses the value provided on instantiation — see options.postid for more.
You should only need to invoke this method after successfully navigating to a new page on a client-side application.
Note: This is always called automatically when creating a new
Vidyinstance.
load()
The method that draws Vidy links around their relevant phrases.
At this point, the SDK expects and traverses text content within the options.content container.
Note: This is called automatically when
options.autoloadis true.
Browser Support
The JavaScript SDK relies on fetch and Promise support, which yields these minimum browsers:
- Edge 14+
- Firefox 40+
- Chrome 42+
- Safari 10.1+
- iOS 10.3+
If your target browser(s) does not support one of these, we'd suggest the unfetch and zousan polyfills, respectively.
License
MIT © VIDY
