Fork me on GitHub

DownloadBuilder.js



Description

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 »



Optional Dependencies


window.btoa and window.atob polyfill - IE < 10 does not support window.atob (necessary to pull files from Github)


Notable Features


Supports Blob URL creation

Supports concatenating local files and/or files from Github

Supports caching ajax/jsonp requests via Session Storage

Library independent


Browser Support


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.


Getting Started

Download the entire project and look at the examples in the demos folder.



Include DownloadBuilder.js

// DownloadBuilder.js
<script src="DownloadBuilder.js" />
          

HTML

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>
          

JavaScript

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

      }
    );

  });

});
          

Options

Here are all of the global and individual options that can be used with DownloadBuilder.js

Global Options

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

Data-Options

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

Methods

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) {});

Contributing

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!


Extending

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!


Donation

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.  


Copyright © 2012 Greg Franko

Published by Github Pages