Learn how to integrate Dashburst DSN into your site.
Last Updated: 2014-11-10 01:00:00 GMT
Dashburst strives to make it as simple as possible to integrate DSN with your site. The Dashburst DSN API is currently in alpha status. Please be aware that there are likely bugs and issues. Use at your own risk. If you have any problems, please contact us by email (listed on the main site).
Javascript is currently the only integration method available. Javascript integration requires the inclusion of a javascript file and a simple <div> with data attributes (referred to below as a "component"). Some attributes are required and some are optional. Check below for details on what is required for each component.
The Javascript file only needs to be included once per page, but it's not a problem if it is included multiple times because it will only run once. Below are two examples of ways to include the javascript code on a page.
The difference between the two versions is that one uses the async attribute. If you are making use of any api settings or method calls, like dsn_api.parse(), then it is recommended to use the version without the async attribute. If you are just loading the code without any custom javascript settings or method calls, then it is recommend to use the async version.
The DSN code uses jQuery. If jQuery is not loaded on the page, then the script will load jQuery itself. If the page already loads jQuery, it is recommended to add the script call after the jQuery script.
<script async src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
<script src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
When the above file is included on a page, it addes four variables to the global namespace: dsn_api_settings, dsn_api, dsn_api_settings_0_1, and dsn_api_0_1. As updates are made to the API, having a version-numbered variable allows you to run two versions of the API on the same page. The non-version-numbered variables are the same as the version-numbered variables if only one version of the API javascript file is included.
If multiple versions of the API are included on the same page, then the non-version-numbered variables are set to the first version that is loaded. If you are not planning to use multiple versions of the API on the same page, it is recommended to use the non-version-numbered variables (like dsn_api_settings and dsn_api) for Javascript API calls so that you can update the version by simply changing the javascript file that is included on the page.
The Javascript API has a limited number of settings that can be changed. When you include the javascript file on a page, it assumes it should immediately find and parse components. The following settings can be changed by setting the dsn_api_settings global variable before loading the javascript file.
| Name | Description | Default |
|---|---|---|
dsn_api_settings.auto |
Expects true or false. If true, then all DSN components on the page are immediately parsed. If false, then no component parsing takes place until explicitly called. | true |
dsn_api_settings.name |
Expects a string that can be used as a javascript variable name. Instead of the version-numbered variable being set to dsn_api_0_1 it allows a custom name to be used. |
'dsn_api_0_1' |
<script>
// Do not parse components on page.
dsn_api_settings = {};
dsn_api_settings.auto = false;
</script>
<script src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
The Javascript API allows a user to make specific method calls from the dsn_api global variable. As mentioned above, the methods rely on jQuery so any method calls should be wrapped in jQuery's document ready code (check out the code example below for details) or inside the dsn_api.ready() method.
| Name | Arguments | Description | Default |
|---|---|---|---|
dsn_api.parse(type, holder, target) |
|||
type |
Expects a string of one of the following values: 'all', 'embed', or 'burst'. Specifies which components should be parsed. |
'all' |
|
holder |
Expects a jQuery selector string (like $('#grandparent div.parent'). It tells the API to only parse components that are children of the holder. |
undefined |
|
target |
Expects a jQuery selector string (like $('#specific'). It tells the API to only parse components that match the selector (if this argument is passed, then holder is ignored). |
undefined |
|
dsn_api.ready(callback) |
|||
callback |
Expects a function. Function will be called when the API has finished initializing. | Required |
<script>
// Do not parse components on page.
dsn_api_settings = {};
dsn_api_settings.auto = false;
</script>
<script src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
<script>
dsn_api.ready(function() {
// After 5 seconds, parse all embed components found in divs with the "content" class.
setTimeout(function() {
dsn_api.parse("embed", "div.content");
}, 5000);
});
</script>
The Burst Button allows users to share content directly from your website. When the Burst Button is clicked, the user is shown a share box that includes the url to share on DSN. You can manually include the url you want shared in the button code or have the button automatically figure out the url to share.
| Attribute | Details |
|---|---|
| class="dsn-api-button" | Required |
| data-dsn-version="0.1" | Required |
| data-design="[DESIGN]" | Required, either "light" or "dark" can be used. |
| data-share-url="[PAGE_URL]" | Optional, if not included defaults to the page where the button is found. |
<div class="dsn-api-button" data-dsn-version="0.1" data-design="light" data-share-url="https://twitter.com/DashBurst/status/412696646065991680"></div>
<script async src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
* Items marked with an asterisk (*) are required.
Embed allows you to include the contents of a DSN update on your own website.
| Attribute | Details |
|---|---|
| class="dsn-api-embed" | Required |
| data-dsn-version="0.1" | Required |
| data-id="[UPDATE_ID]" | Required, the id of the update you want to embed. |
<div class="dsn-api-embed" data-id="262" data-dsn-version="0.1"></div>
<script async src="https://api.dashburst.com/js/dsn-0.1.js" charset="utf-8"></script>
* Items marked with an asterisk (*) are required.
This is the initial developer document so there are no changes to list.