How to make an exhibit from any JSONP data source

From SIMILE Widgets
Jump to: navigation, search

You should follow the Getting Started Tutorial first. This tutorial is for connecting any data source already JSONP native by design, and converting it into Exhibit's JSON format, if not already so right off the bat.

Let's start with an easy example, where it's just connecting the dots because the input format already is as expected, and (at least very nearly) JSONP (save the dynamically allocated callback), like if you ostensibly followed this old EditGrid article. In this case, the data set conforms to Exhibit's preferences but we need to describe to give Exhibit the name of the callback used to consume the data set -- like this font exhibit, which feeds its set of default fonts from http://www.editgrid.com/user/ecmanaut/font-names.exhibit.jsonp. Assuming the data set was Exhibit JSON and the URL provided full JSONP support, you would have included it like this: <js>

<link rel="exhibit/data" type="application/jsonp"
      href="http://www.editgrid.com/user/ecmanaut/font-names.exhibit.jsonp" />

</js> In this case, however, the callback name is a fix "editgridCallback", and we need to tell Exhibit about it (this also means that we can not have two data sources using that same name, which is why proper JSONP is better, which entails being able to set any callback name by appending "?callback=wantedname" to the URL, letting Exhibit pick a name that does not conflict with any other JSONP data source used -- Exhibit does this for you, if you don't tell it otherwise -- and if the URL query parameter is named something nonstandard instead of "callback", just make sure your href ends in "?cb=", or whatever it was named): <js>

<link rel="exhibit/data" type="application/jsonp"
      href="http://www.editgrid.com/user/ecmanaut/font-names.exhibit.jsonp"
      ex:jsonp-callback="editgridCallback" />

</js> If you peek closely at that exhibit, you'll note that it adds another property too: <js>

<link rel="exhibit/data" type="application/jsonp"
      href="http://www.editgrid.com/user/ecmanaut/font-names.exhibit.jsonp"
      ex:jsonp-callback="editgridCallback" ex:converter="fontConverter" />

</js> This is for specifying a method which changes the format (or even content) of the data set fed to Exhibit, to convert or massage it into Exhibit's format using a custom javascript function of yours. Save this for when you really need it, as it breaks a fundamental feature of Exhibit's sharing, making other people wanting to reuse your data set dependent on more than your data set. This example uses a function which adds some data to each element based on measuring font sizes and availability on the browser that visits it:

<geshi lang=javascript>

<script>
function fontConverter( json ) {
  var items = json.items;
  for (var i = 0; item = items[i]; i++) {
    items[i] = measureFontSize( item );
  }
  return json;
}
</script>

</geshi> This way, any data set, regardless of JSON structure, can be reshaped to fit Exhibit's preferences, using a converter that massages the data with a bit of javascript code, and returns Exhibit JSON. You can make some pretty interesting mashups this way right in Exhibit, using any of the web's JSON APIs out there. They are growing more abundant by the day.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox