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     
 66     /**
 67      * Host url - default to freebase.com
 68      * @name TimeMap.loaders.metaweb#HOST
 69      * @type {String}
 70      */
 71     loader.HOST = options.host || "http://www.freebase.com";
 72     /**
 73      * Service path - default to freebase.com default
 74      * @name TimeMap.loaders.metaweb#QUERY_SERVICE
 75      * @type {String}
 76      */
 77     loader.QUERY_SERVICE = options.service || "/api/service/mqlread";
 78 
 79     /**
 80      * URL built using encoded query text and the callback name
 81      * @name TimeMap.loaders.metaweb#url
 82      * @type {String}
 83      */
 84     loader.url = loader.HOST + loader.QUERY_SERVICE + "?queries=" + querytext + "&callback=";
 85     
 86     /**
 87      * Preload function for Metaweb
 88      * @name TimeMap.loaders.metaweb#preload
 89      * @function
 90      * @parameter {Object} data     Data to preload
 91      * @return {Array} data         Array of item data
 92      */
 93     loader.preload = function(data) {
 94         // Open outer envelope
 95         var innerEnvelope = data.qname;
 96         // Make sure the query was successful
 97         if (innerEnvelope.code.indexOf("/api/status/ok") !== 0) {
 98             // uncomment for debugging
 99             /*
100             // If error, get error message and throw
101             var error = innerEnvelope.messages[0];
102             throw error.code + ": " + error.message;
103             */
104             return [];
105         }
106         // Get result from inner envelope
107         return innerEnvelope.result;
108     };
109 
110     return loader;
111 };
112