Getting Started

From SIMILE Widgets
Revision as of 13:40, 17 February 2012 by Mwaters (Talk | contribs)
Jump to: navigation, search

Contents

Getting Started with Exhibit 3.0

Exhibit publishes your data collections on the Web in rich, interactive pages. Exhibit 3.0 has two modes: Scripted mode for running smaller exhibits and Staged mode for larger, server-based exhibits.

This tutorial walks you through the basic steps for creating a simple exhibit in Scripted mode. This example uses XHTML. To see Exhibit 3.0 running with HTML5, see the demo server.

For details on running Staged mode, see the developer documentation on GitHub.

The Basics

Publishing data with the Scripted mode of Exhibit is very simple. You need three basic components.

  • Connection to Exhibit scripts either remotely or on your own Web server
  • Data file containing your data, in JSON format (more on that later)
  • HTML page that calls the Exhibit scripts and displays your page content when loaded in the browser

Tutorial: Creating an Exhibit with Scripted Mode

Let's dive right in. First, you'll build the HTML and data files Exhibit uses to publish data. After you've published an Exhibit, you can refine how the page displays, see which display options work best for you, and tweak the page design as needed.

We assume you know some basic HTML. We'll use sample code and data about MIT's Nobel Prize winners, but you can also substitute your own data. If you get lost or need help along the way, see the finished HTML file at the end of the tutorial.

Creating Your HTML Page

Start with a basic text editor (Notepad on Windows or TextEdit on the Mac).

  • Create an HTML file in your text editor.
  • If you're following our demo example, copy this text and name the file nobelists.html.

Sample Exhibit HTML Text

<html>
 <head>
 <title> Exhibit | Examples | MIT Nobel Prize Winners</title>

 <link href="nobelists.js" type="application/json" rel="exhibit-data" />
    <!-- Replace the URL here with your Exhibit 3.0 script location -->  

    <script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/exhibit-api.js” type= "text/javascript"></script>
    <style>
    </style>
 </head> 
 <body>
    <div id="main-content">
        <div id="title-panel">
            <h1>63 MIT-related Nobel Prize Winners</h1>
  </div>
    
        <div id="top-panels">
            <table width="100%"><tr>
             Facets for sorting and browsing go here</tr></table>
        </div>
        
<div ex:role="viewPanel" style="padding: 1em 0.5in;">
        
            <div ex:role="view"
                ex:label="Details"
                ex:viewClass="Tile"
                ex:showAll="true"
               </div>
                             
            </td>
        </tr>
    </table>
 </table>
        
 </body>
 </html>


In the code example:

  1. You must point Exhibit to your data file. Ours is named nobelists.js. It's identified as JSON format.
  2. Point to the Exhibit JavaScript needed to run Exhibit: http://api.simile-widgets.org/exhibit/3.0.0rc1/exhibit-api.js
    The Exhibit codes beginning with ex: publish a basic view of your data.
    This is the most basic HTML text for an Exhibit file. We'll start with the bare bones and add browsing controls and styling as we go.
  3. Save the file as nobelists.html in any folder you choose.

Next, you prepare a data file, in a format Exhibit can read (JSON), containing your data collection, and save it to the same folder.

Preparing Your Data File in JSON Format

Your data must be structured and formatted so Exhibit can read, publish, filter, sort, and display the data.

We’ve prepared a sample data file with data about Nobel Prize winners.

  1. Download the sample data file nobelists.js from the Exhibit 3 wiki page. http://simile-widgets.org/wiki/Exhibit3
  2. Save nobelists.js to the same folder where you saved the HTML file, nobelists.html.

Exhibit looks for your data to be structured in JSON format.

"items" : [

        {   "type":                "Nobelist",
            "label":               "Burton Richter",
            "discipline":          "Physics",
            "shared":              "yes",
            "last-name":           "Richter",
            "nobel-year":          "1976",
            "relationship":        "alumni",
            "co-winner":           "Samuel C.C. Ting",
            "relationship-detail": "MIT S.B. 1952, Ph.D. 1956",
            "imageURL": 
"http://nobelprize.org/nobel_prizes/physics/laureates/1976/richter_thumb.jpg"

        },

In this sample JSON-formatted data, each Nobel winner’s data is an item, containing a series of fields such as type, label (or name), discipline, and so on.

Publishing an Exhibit View

Once you’ve got the HTML and JSON data files, publishing an Exhibit is quite simple.

  1. Go to the directory where you saved the two files: nobelists.html and nobelists.js (using Explorer on Windows or Finder on Mac).
  2. Drag nobelists.html into your Web browser.
    Behind the scenes, Exhibit marries your structured JSON data with the HTML display template.
  3. Notice the page displays each Nobelist’s data as listed in the JSON file.

You’ve published your first Exhibit! You should now see a Web page that shows 63 people's names and information. So far, it’s a pretty basic display, using the Exhibit’s most basic display, the List View.

Exhibit makes it easy to add sorting, filtering, and faceting to your data display.

In the next section, you’ll learn different ways to present and sort your data.

You’ll also have the chance to adjust the page content. Note the title that says "63 Nobelist" instead of "63 Nobelists"—you’ll fix that later, too.

Facets: Adding Data Filtering, Searching, and Sorting

Your exhibit so far shows a lot of details but in a long list. Next you’ll learn how to add optional facets for filtering or sorting data – all done in the browser without complicated programming.

Filtering

Looking at each person's entry in the list view, you see several fields such as "discipline" (the field in which they won their Nobel prize), "relationship" (how they're related to MIT), "shared" (whether they received their prize alone or shared it with others), etc. These fields provide useful ways to sort and filter the data set.

In the HTML code (nobelists.html) find the text "browsing controls here..." and replace it with

<div id="top-panels">
  <table width="100%"><tr>
  <td><div ex:role="facet" 
ex:expression=".discipline" 
ex:facetLabel="Discipline"></div></td>
  <td><div ex:role="facet" 
ex:expression=".relationship" 
ex:facetLabel="Relationship"></div></td>
  <td><div ex:role="facet" ex:expression=".shared" 
ex:facetLabel="Shared?"></div></td>
  <td><div ex:role="facet" ex:expression=".deceased" 
ex:facetLabel="Deceased?"></div></td>
  </tr></table>
 </div>

Save the file in your text editor, switch back to your browser, and reload the nobelists.html file. Now you should see a row of boxes across the top labeled Discipline, Relationship, Shared, and Deceased. These boxes are called facets -- different angles or aspects of the data that help users analyze the data set.

Notice the gray numbers in front of the values inside these facets. In the facet called Discipline, the number "2" in front of "Peace" tells you there are 2 people who received the Nobel Peace prize. Click on "Peace" and the page now shows only those 2 people (rather than 63 people originally).

By adding those HTML div elements as shown above, you've implemented filtering in about 10 seconds. (If you've ever done server-side programming, you might consider how long it would have taken you to implement filtering using whatever server-side publishing frameworks you're familiar with.)

You can also add text search to your exhibit by adding a facet of type TextSearch:

<div ex:role="facet" ex:facetClass="TextSearch"></div>

As you type into the search text box, the exhibit gets filtered.

Sorting

Using Exhibit's basic view, you can already change the sorting order of the Nobelists by clicking on sorted by and choosing labels. But if you want to set a specific sorting order at the beginning -- for example, to sort by the discipline and year each person won the prize -- you can change <div ex:role="view"></div> to:

<div ex:role="view" ex:orders=".discipline, .nobel-year"></div>


You can also restrict the properties by which your users can sort by using the ex:possibleOrders attribute:

<div ex:role="view"
  ex:label="Details"
  ex:viewClass="Tile"
  ex:showAll="true"
  ex:orders=".discipline, .nobel-year"
  ex:possibleOrders=".label, .last-name, .discipline, 
 .relationship, .shared, .deceased, .nobel-year">
 </div>

Inspecting Your Data File

So far, you've prepared only two files: an .html file and a .js file. One specifies the presentation of the Web page in HTML and the other stores the data in JSON format.

Open up the file nobelists.js in your text editor and take a look at it. It's written in the JSON format. There is an array of items (think of them as database records). Each item looks like this:

{  "type":                 "Nobelist",
            "label":                "Horst L. St\u00F6rmer",
            "discipline":           "Physics",
            "shared":               "yes",
            "last-name":            "St\u00F6rmer",
            "nobel-year":           "1998",
            "relationship":         "research",
            "co-winner":           [
                "Robert B. Laughlin",
                "Daniel C. Tsui"
            ],
            "relationship-detail": "MIT researcher at MIT Magnet Lab",
            "imageURL": 
"http://nobelprize.org/nobel_prizes/physics/laureates/1998/stormer_thumb.jpg"
        },

editing text continue at tutorial2

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox