A JavaScript library that uses the HTML5 Filesystem API to create concatenated single file custom builds for front-end projects.
The library currently supports concatenating local files (supported in all major browsers) and/or files from Github (not supported in IE unless you use a window.atob polyfill). The library also uses Session Storage to provide an option to cache ajax/jsonp requests. If you are using a browser that does not support the HTML5 Filesystem, the text of the concatenated file will still be available to provide users with the custom build code, just not a separate file link to it.
DownloadBuilder.js is heavily influenced by Eric Bidelman (a member of the Google Chrome Developer Relations Team). Eric has been a big supporter of the HTML5 Filesystem API and without his HTML5 Rocks articles and HTML5 Filesystem O'Reilly Book, this library would not have been created. The project is also heavily influenced by Oscar Goodson's JSONP project and James Ward's Github File Download project.
The project is hosted on Github and is available for use under the MIT software license. You can report bugs and discuss features on the GitHub issues page, or send tweets to Greg Franko.
Fork on Github » View Project Example »
window.btoa and window.atob polyfill - IE < 10 does not support window.atob (necessary to pull files from Github)
Supports Blob URL creation
Supports concatenating local files and/or files from Github
Supports caching ajax/jsonp requests via Session Storage
Library independent
Only Google Chrome fully supports the HTML5 Filesystem API. This means that only Google Chrome supports creating a custom build url.
All Major Browsers (IE8+, Firefox, Chrome, Safari) support retrieving local files and concatenating them.
Firefox, Chrome, and Safari all support retrieving Github files. If you include the window.atob polyfill, then IE8+ will also support retrieving Github files.
Download the entire project and look at the examples in the demos folder.
// DownloadBuilder.js
<script src="DownloadBuilder.js" />
Create one checkbox for each file in your project that you want to allow users to download. Each checkbox value should be the full file path.
Note: You can use Github or local relative file paths. This example uses Github and more information on setting up a link to a Github repository is in the JavaScript documentation.
// A checkbox with the correct Github filepath of testfile.js
<label class="checkbox"><input checked="checked" type="checkbox" value="src/javascripts/testfile.js">Test File</label>
Using a library (eg. jQuery) or regular JavaScript, create a new DownloadBuilder object instance with custom options when the DOM is ready.
Note: You do not need to use a library, such as jQuery. I am using it here for convenience. Also, all options are optional and more documentation about all of the options can be found further down in the documentation.
//Executes your code when the DOM is ready. Acts the same as $(document).ready().
$(function() {
// All options passed to the DownloadBuilder object constructor are optional
// This example is a sample Github setup
var builder = new DownloadBuilder({
"location": "github",
"author": "gfranko",
"repo": "jquery.selectboxit.js",
"branch": "dev"
});
});
Call the buildURL() method to construct a file url (if supported).
Note: More documentation about the buildURL method and other methods can be found further down in the documentation.
//Executes your code when the DOM is ready. Acts the same as $(document).ready().
$(function() {
// All options passed to the DownloadBuilder object constructor are optional
// This example is a sample Github setup
var builder = new DownloadBuilder({
"location": "github",
"author": "gfranko",
"repo": "jquery.selectboxit.js",
"branch": "dev"
});
// Whenever an element with an id of css-generate is clicked, the buildURL() method is called
$("#css-generate").on("click", function() {
// Pass in all of the checkboxes that should be used to download files, the desired name of the file to be created,
// the type of file to be created, and a callback function
builder.buildURL($("#css-downloads input[type='checkbox']:checked"), "jquery.selectboxit.css", "css",
function(data) {
// An object is passed to the callback function which contains a file url
// (if the current browser supports the HTML5 Filesystem API), file content (the text of the file),
// the name of the file that was created, and the type of file that was created.
// Put any custom logic here
}
);
});
});
Here are all of the global and individual options that can be used with DownloadBuilder.js
Here are global options that can be set when a new DownloadBuilder instance is created: var builder = new DownloadBuilder({ });
Note: All global options can be overriden per checkbox by specifying data attributes on a checkbox. This documentation can be found in the Data Options Section below.
| Name | Type | Default | Parameters |
|---|---|---|---|
| cache | Number (milliseconds) | 3600000 (one hour) | Any number |
| location | String | "local" | "local" or "github" |
| author | String | "" | Any valid Github username |
| repo | String | "" | Any valid Github repository name |
| branch | String | "" | Any valid Github repository branch name |
| client_id | String | "" | Any valid Github Oauth Client Id |
| client_secret | String | "" | Any valid Github Oauth Client Secret |
Here are individual options that can be set on each checkbox to override a global option of a DownloadBuilder instance.
Note: All other checkbox's that do not have these data-options will continue to use the global options set on the DownloadBuilder instance.
| Name | Type | Default | Parameters |
|---|---|---|---|
| data-location | String | "local" | "local" or "github" |
| data-author | String | "" | Any valid Github username |
| data-repo | String | "" | Any valid Github repository name |
| data-branch | String | "" | Any valid Github repository branch name |
Here are methods that can be called once a DownloadBuilder instance is created: var builder = new DownloadBuilder({ });
| Name | Parameters | Example |
|---|---|---|
| buildURL | DOM Checkbox Elements, String file name, String file type, Function callback | builder.buildURL($("#css-downloads input[type='checkbox']:checked"), "jquery.selectboxit.css", "css", function(data) {}); |
| createURL | Object Literal: String file name, String file type, String file content, Function callback | builder.createURL({ "lang": "css", "fileName": "test", "data": "body { color: red; }", "callback": function(url) {} }); |
| JSONP | String url, String method name (optional), Function callback | this.JSONP("someURL", function(data) {}); |
Take care to maintain the existing coding style. Add Jasmine unit tests for any new or changed functionality. Lint and test your code using Grunt.
After you have verified your code, send a pull request to the Downloadbuilder dev branch. After you send a pull request, you will hear back from me shortly after I review your code. You’ll find source code in the src subdirectory!
If you find that you need a feature that DownloadBuilder.js does not currently support, either let me know via the Github issue tracker, or fork the project and and easily extend DownloadBuilder.js!
If you would like to support the DownloadBuilder.js project, please consider sending a donation to Greg Franko (the project maintainer). All donations (small or large) are appreciated and help the continued development of the project.