Getting Started

From SIMILE Widgets
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>
             <td>Facets for sorting and browsing go here</td>
            </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>
        </div>
                                   
     </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"
        },

That's basically a set of properties and property values. For example, the property shared has the value "yes". Horst L. Störmer won his Nobel prizes with two other people, and so the property co-winner has two values, which are encoded as elements of an array. That just means you list the values between [ and ], separated by commas.

Properties whose names contain non-alphanumeric characters (such as last-name) must be surrounded by double or single quotes. But if you don't like to quote property names, you can use a different naming convention (for example, imageURL instead of "image-url").

Note: Exhibit 3.0 is stricter about JSON formatting than prior versions of Exhibit. If you're seeing errors in JSON data, try using a validator like JSONlint to check your data formatting: http://jsonlint.com/

Required Data Values

Each item in your data file must have a label property value. (There are exceptions but this is required for 99% of the cases.) The type property value specifies the type of the item; otherwise, the item's type defaults to Item. In our data file, we set the type property to Nobelist.

Aside from these few restrictions, you can put pretty much anything into your data file.


How Does Exhibit Work?

The file nobelists.html has a reference to the JavaScript file exhibit-api.js. That's how you include Exhibit. Here's roughly what happens when the web page is loaded:

  1. The code of exhibit-api.js is loaded and it automatically pulls in some more code.
  2. A lightweight database is created and the data files are loaded into it.
  3. An Exhibit object is created. It reads the various ex: attributes in the HTML code to configure its user interface. It then reads data out of the lightweight database and constructs its user interface

For Exhibit 3.0 Scripted mode, remember that everything happens inside the Web browser. The user's Web browser loads the entire data set in memory and performs all computation (sorting, filtering, etc.) locally, which provides much of the power of the Exhibit approach.

Note that so far in this tutorial, you haven't had to install, configure, or manage a database or to write a single line of server-side script (in PHP, ASP, JSP, CGI, etc.).

Learn More About Staged Exhibit

For Exhibit 3.0 Staged mode, a server handles filtering, sorting, and data manipulation. See the Exhibit 3.0 Staged documentation for details.

Lenses: Styling How Your Exhibit Displays

Right now the information about each Nobelist is displayed in a table showing an item's property and value. Exhibit uses lenses to style the HTML displaying your data in the browser. For example, you might use lenses to show images for each item in an exhibit.

Insert this table inside the div element with the id exhibit-view-panel (either before or after the inner div element that is already there):

 <table ex:role="lens" class="nobelist" style="display: none;"><tr>
  <td><img ex:src-content=".imageURL" /></td>
  <td>
  <div ex:content=".label" class="name"></div>
  <div>
  <span ex:content=".discipline" class="discipline"></span>, 
  <i ex:content=".nobel-year"></i></div>
  <div ex:if-exists=".co-winner" class="co-winners">
    Co-winners: <span ex:content=".co-winner"></span>
    </div>
  <div ex:content=".relationship-detail" class="relationship"></div>
   </td></tr>
 </table>

Then, find the style element at the start of the HTML code and change it as follows:

<style>
body {
font-size: 75%;
margin: 0;
padding: 0;
font-family: "Lucida Grande","Tahoma","Helvetica","Arial",sans-serif;
color: #222;
}
table, tr, td {
font-size: inherit;
}
tr, td {
vertical-align: top;
}
img, a img {
border: none;
}
#main-content { background: white; }
#title-panel { padding: 0.25in 0.5in; }
#top-panels {
padding: 0.5em 0.5in;
border-top: 1px solid #BCB79E;
border-bottom: 1px solid #BCB79E;
background: #FBF4D3;
}
.exhibit-tileView-body { list-style: none; }
.exhibit-collectionView-group-count { display: none; }
table.nobelist {
border: 1px solid #ddd;
padding: 0.5em;
margin: 0.5em 0;
display: block;
}
div.name {
font-weight: bold;
font-size: 120%;
}
.relationship {
color: #888;
}
div.nobelist-thumbnail {
float: left;
width: 13em;
height: 10em;
border: 1px solid #BCB79E;
background: #F0FFF0;
padding: 1em;
margin: 0.5em;
text-align: center;
}
div.nobelist-timeline-lens {
padding: 1em;
text-align: center;
}
 </style>

Save and reload in the browser. The Nobelists file looks much better, and you've been able to customize its display to emphasize names and photos for each Nobel winner.

What you have just done is specifying an exhibit lens template and some CSS styles. Exhibit uses a lens template to generate the display for each Nobelist. In the lens template, the ex:content attribute values specify which item properties Exhibit uses to fill the corresponding HTML elements. For example,

<div ex:content=".label" class="name"></div>

causes a div element to be generated using the label property value of the Nobelist -- the person's name.

Adding Images

In addition to generating text, you can also generate images by including an img element and specifying its src attribute value to be generated, in our example, from the imageURL property value in the nobelists.js file:

<img ex:src-content=".imageURL" />


Customizing Exhibit Attributes To generate any attribute value in Exhibit, you prepend its name with ex: and append -content. So if your data file contains a field called publication-date, you can display those dates in a lens by using

<div ex:content=".publication-date" />


Note that some Nobelists have co-winners recorded in the data file, but not all. (We only have information about co-winners who are also related to MIT.) For conditional content like this, you use the ex:if-exists attribute value to include a part of the template conditionally:

<div ex:if-exists=".co-winner" class="co-winners">Co-winners:

<span ex:content=".co-winner"></span>

</div>

Without the code ex:if-exists, the page would show a lot of "Co-winners:" with nothing in the data field.

Schema

Properties

In your Web browser, filter the "discipline" facet to show only "Physics", "relationship" to only "research", and "shared" to "yes". You should get 5 Nobelists.

Note that the Nobelist, Horst L. Störmer, shared his prize with two others: Robert B. Laughlin and Daniel C. Tsui. You can readily see Daniel C. Tsui listed with Störmer, but Laughlin's data doesn't display because he's not a researcher and has been filtered out.

However, Laughlin does appear in the rendition of Störmer, so it would be nice to be able to click on Laughlin's name and get some information about him right there and then. We can do this by adding some schema to our data, to say that co-winner property values, such as "Robert B. Laughlin", actually mean items.

Open the file nobelists.js and modify the beginning so that it looks like this:

  {
       "properties": {
           "co-winner" : {
               "valueType": "item"
           }
       },
       "items" : [
           {   "type":       "Nobelist",
               "label":      "Burton Richter",
               "discipline": "Physics",
               "shared":     "yes",
   
   
   ...the rest of the file...

Now, open up another browser window (or tab) and drag the file nobelists.js into it and make sure that the latest version is displayed. If not, hit the browser's Refresh button. Once that's done, switch to the browser window displaying that HTML file and refresh it. Select the same filters as above. You should now see that Robert B. Laughlin's name appears in blue and is underlined. Click on it.

Types

Notice that the number of Nobelists shown on the page is ungrammatical -- it reads "5 Nobelist" instead of "5 Nobelists". Modify the beginning of the file nobelists.js as follows:

{
"types": {
"Nobelist" : {
"pluralLabel": "Nobelists"
}
},
"properties": {
"co-winner": {
"valueType": "item"
}
},
...the rest of the file...


Save your data file, switch to the browser window displaying the .js file, and refresh it. Then switch to the window displaying the .html file and refresh it to see the change.

The key point of this step is that the Web page can look and behave better not just by fine-tuning the HTML code but also by improving the data.

Adding Additional Views

Thumbnail View

Exhibit offers several different Views to display data. With a series of images and short descriptors, the Thumbnail View comes in handy for browsing and sorting a data set like ours. An exhibit can use several different views. Add this code to nobelists.html after the Lens table:

<div ex:role="view"
              ex:viewClass="Thumbnail"
              ex:showAll="true"
              ex:orders=".discipline"
              ex:possibleOrders=".label, .last-name, 
.discipline, .relationship, .shared, .deceased, .nobel-year">
   <div ex:role="lens" class="nobelist-thumbnail" style="display: none;">
              <img ex:src-content=".imageURL" />
              <div><span ex:content=".label"></span></div>
              <div>
              <span ex:content=".discipline" class="discipline"></span>, 
              <span ex:content=".nobel-year" class="year"></span>
              </div>
              </div>
              </div>

Save the file and open it in your browser window. The Thumbnail View is quite handy for showing images and sorting by a particular data field, such as discipline or year.

Timeline View

For data that relates to history or includes time fields, the Timeline Widget adds an interesting dimension to your exhibit.

The nobelists.js data file lists the years when the Nobelists won their prizes, so we can plot each one on a time line. To display timelines in Exhibit you need to include a separate utility, the Timeline widget. The Timeline widget is a bit bulky, so Exhibit doesn't include it by default. You have to include the time extension to Exhibit. Open the file nobelists.html, find the reference to exhibit-api.js and add the following script element after it:

<script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/extensions/time/time-extension.js" 
type="text/javascript"></script>

Then add this view after the Thumbnail view code block:

<div ex:role="view"
  ex:viewClass="Timeline"
  ex:start=".nobel-year"
  ex:colorKey=".discipline"
  ex:bubbleWidth="150"
  ex:bubbleHeight="150">
 <div ex:role="lens" class="nobelist-timeline-lens" style="display: none;">
   <img ex:src-content=".imageURL" />
   <div><span ex:content=".label"></span></div>
   <div>
    <span ex:content=".discipline" class="discipline"></span>, 
    <span ex:content=".nobel-year" class="year"></span>
   <div>
 </div>
 </div>

Save and reload in the browser. That's it!

Exhibit Timeline View

This view shows the timeline -- notice you can toggle to another view by clicking Thumbnails or Details. Also, note the red flag that appears on the right side of the browsing window, in the Exhibit control panel -- this Bookmarking tool lets users copy the current URL to save this view or share it with others.

Formatting Notes

If you want the timeline and tile views to be stacked up, rather than shown as tabs, remove the ex:role="viewPanel" attribute to a simple td above the "lens" table.

<td ex:role="viewPanel">

The ex:start attribute value in the code you just inserted specifies which property to use as the starting date/time, and the ex:colorKey attribute value specifies which property to use to color-code the markers on the time line.

Final HTML Code

See the final HTML file that publishes the Nobelists exhibit.

Summary and Next Steps

This tutorial shows you how to start making an exhibit by creating two files:

  • An HTML file with formatting and Exhibit codes, nobelists.html
  • Your data formatted in a JSON data file, nobelists.js

Then, by adding more code to the HTML file or the JSON file, you make the exhibit Web page look and behave better--supporting filtering and sorting, providing more views, presenting items in custom ways, etc. Using the Scripted mode of Exhibit, you can accomplish this without ever touching a Web server or a database.

To get more involved with Exhibit, explore the online demos, subscribe to the mailing list, and contribute your expertise to the community.

Exhibit Demos

The Nobelists HTML and JSON files are available on the Exhibit demo server. This example uses XHTML. To see Exhibit 3.0 running with HTML5, see the Senate demo here: http://databench.zepheira.com/demos/senate/html5.html

The Exhibit demos are a great showcase for a variety of ways you can use Exhibit, both Scripted and Staged modes. Use them to get ideas, find code samples, and kick-start your own exhibits.

Developers: Learn More About Exhibit

For software developers who would like to dig into the details of Exhibit coding, see the Exhibit API doc online: https://ci.zepheira.com/job/test_exhibit3/javadoc/index.html.

You can also learn more about customizing and extending Exhibit to add your own widgets and views.

Troubleshooting

If your Exhibit code doesn't display as expected, check these things:

  • Does your HTML file call the correct data file in the code? Check this line: <link href="nobelists.js"...>
  • If you see JSON errors in your browser, double check your data file by running it through JSONlint or another data validator. Exhibit 3.0 applies stricter JSON standards than Exhibit 2 did.
  • Is your script tag pointing to a working installation of Exhibit 3.0? The Exhibit community hosts a working installation here: http://api.simile-widgets.org/exhibit/3.0.0rc1/exhibit-api.js
  • If the HTML header and title load, but your data does not display, double check the URL you're using to call the Exhibit JavaScript. Exhibit needs to be loaded and running in your Web server.
  • Open your browser's error console to check whether Exhibit reported errors that might help guide you to a solution.
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox