1 /* 
  2  * Timemap.js Copyright 2010 Nick Rabinowitz.
  3  * Licensed under the MIT License (see LICENSE.txt)
  4  */
  5  
  6 /**
  7  * @fileOverview
  8  * Metaweb Loader
  9  *
 10  * @author Nick Rabinowitz (www.nickrabinowitz.com)
 11  */
 12  
 13 // for JSLint
 14 /*global TimeMap */
 15 
 16 /**
 17  * @class
 18  * Metaweb loader: Load data from freebase.com.
 19  *
 20  * <p>This is a loader for data from the Metaweb service at freebase.com. See
 21  * the API documentation at <a href="http://www.freebase.com/docs/mql/ch01.html">http://www.freebase.com/docs/mql/ch01.html</a> for
 22  * a description of how to write MQL queries. This code is based on code from
 23  * the API site.</p>
 24  *
 25  * @augments TimeMap.loaders.jsonp
 26  * @requires lib/json2.pack.js
 27  * @requires loaders/jsonp.js
 28  *
 29  * @example
 30 TimeMap.init({
 31     datasets: [
 32         {
 33             title: "Freebase Dataset",
 34             type: "metaweb",
 35             options: {
 36                 query: [
 37                     {
 38                       // query here - see Metaweb API
 39                     }
 40                 ],
 41                 transformFunction: function(data) {
 42                     // map returned data to the expected format - see
 43                     // http://code.google.com/p/timemap/wiki/JsonFormat
 44                     return data;
 45                 }
 46             }
 47         }
 48     ],
 49     // etc...
 50 });
 51  * @see <a href="../../examples/artists.html">Metaweb Example</a>
 52  *
 53  * @param {Object} options          All options for the loader
 54  * @param {Object} options.query                MQL query to load
 55  * @param {Function} options.transformFunction  Function to call on individual items before loading
 56  * @param {String} [options.host=http://www.freebase.com]   Host url of web service
 57  * @param {String} [options.service=/api/service/mqlread]   Path to web service on host
 58  * @param {mixed} [options[...]]    Other options (see {@link TimeMap.loaders.jsonp})
 59  */
 60 TimeMap.loaders.metaweb = function(options) {
 61     var loader = new TimeMap.loaders.jsonp(options),
 62         q = options.query || {},
 63         // format the query URL for Metaweb
 64         querytext = encodeURIComponent(JSON.stringify({qname: {query: q}})),
 65         host = options.host || "http://www.freebase.com",
 66         service = options.service || "/api/service/mqlread";
 67     
 68     // set url
 69     loader.opts.url = host + service + "?queries=" + querytext + "&callback=?";
 70     
 71     /**
 72      * Preload function for Metaweb
 73      * @name TimeMap.loaders.metaweb#preload
 74      * @function
 75      * @parameter {Object} data     Data to preload
 76      * @return {Array} data         Array of item data
 77      */
 78     loader.preload = function(data) {
 79         // Open outer envelope
 80         var innerEnvelope = data.qname;
 81         // Make sure the query was successful
 82         if (innerEnvelope.code.indexOf("/api/status/ok") !== 0) {
 83             // uncomment for debugging
 84             /*
 85             // If error, get error message and throw
 86             var error = innerEnvelope.messages[0];
 87             throw error.code + ": " + error.message;
 88             */
 89             return [];
 90         }
 91         // Get result from inner envelope
 92         return innerEnvelope.result;
 93     };
 94 
 95     return loader;
 96 };
 97