1 /* 
  2  * Timemap.js Copyright 2010 Nick Rabinowitz.
  3  * Licensed under the MIT License (see LICENSE.txt)
  4  */
  5 
  6 /**
  7  * @fileOverview
  8  * JSON Loaders (JSONP, JSON String)
  9  *
 10  * @author Nick Rabinowitz (www.nickrabinowitz.com)
 11  */
 12  
 13 // for JSLint
 14 /*global TimeMap */
 15 
 16 /**
 17  * @class
 18  * JSONP loader - expects a service that takes a callback function name as
 19  * the last URL parameter.
 20  *
 21  * <p>The jsonp loader assumes that the JSON can be loaded from a url to which a 
 22  * callback function name can be appended, e.g. "http://www.test.com/getsomejson.php?callback="
 23  * The loader then appends a nonce function name which the JSON should include.
 24  * This works for services like Google Spreadsheets, etc., and accepts remote URLs.</p>
 25  *
 26  * @augments TimeMap.loaders.remote
 27  *
 28  * @example
 29 TimeMap.init({
 30     datasets: [
 31         {
 32             title: "JSONP Dataset",
 33             type: "jsonp",
 34             options: {
 35                 url: "http://www.example.com/getsomejson.php?callback="
 36             }
 37         }
 38     ],
 39     // etc...
 40 });
 41  *
 42  * @constructor
 43  * @param {Object} options          All options for the loader:
 44  * @param {String} options.url          URL of JSON service to load, callback name left off
 45  * @param {mixed} [options[...]]        Other options (see {@link TimeMap.loaders.remote})
 46  */
 47 TimeMap.loaders.jsonp = function(options) {
 48     var loader = new TimeMap.loaders.remote(options);
 49     
 50     /**
 51      * JSONP load function. Creates a callback function and adds a script tag
 52      * with the appropriate URL to the document, triggering the HTTP request.
 53      * @name TimeMap.loaders.jsonp#load
 54      * @function
 55      *
 56      * @param {TimeMapDataset} dataset  Dataset to load data into
 57      * @param {Function} callback       Function to call once data is loaded
 58      */
 59      loader.load = function(dataset, callback) {
 60         // get loader callback name
 61         var callbackName = this.getCallbackName(dataset, callback),
 62             // create a script tag
 63             script = document.createElement("script");
 64         // set the src attribute and add to the document
 65         script.src = this.url + "TimeMap.loaders.cb." + callbackName;
 66         document.body.appendChild(script);
 67     };
 68     
 69     return loader;
 70 };
 71 
 72 /**
 73  * @class
 74  * JSON string loader factory - expects a plain JSON array.
 75  *
 76  * <p>The json_string loader assumes an array of items in plain JSON, with no
 77  * callback function - this will require a local URL.</p>
 78  * <p>Note that this loader requires lib/json2.pack.js.</p>
 79  *
 80  * @augments TimeMap.loaders.remote
 81  *
 82  * @requires lib/json2.pack.js
 83  *
 84  * @example
 85 TimeMap.init({
 86     datasets: [
 87         {
 88             title: "JSON String Dataset",
 89             type: "json_string",
 90             options: {
 91                 url: "mydata.json"    // Must be a local URL
 92             }
 93         }
 94     ],
 95     // etc...
 96 });
 97  *
 98  * @param {Object} options          All options for the loader
 99  * @param {String} options.url          URL of JSON file to load
100  * @param {mixed} [options[...]]        Other options (see {@link TimeMap.loaders.remote})
101  */
102 TimeMap.loaders.json_string = function(options) {
103     var loader = new TimeMap.loaders.remote(options);
104     
105     /**
106      * Parse a JSON string into a JavaScript object, using the json2.js library.
107      * @name TimeMap.loaders.json_string#parse
108      * @function
109      * @param {String} json     JSON string to parse
110      * @returns {Object}        Parsed JavaScript object
111      */
112     loader.parse = JSON.parse;
113     
114     return loader;
115 };
116 
117 // Probably the default json loader should be json_string, not
118 // jsonp. I may change this in the future, so I'd encourage you to use
119 // the specific one you want.
120 TimeMap.loaders.json = TimeMap.loaders.jsonp;
121