Tutorial2

(Difference between revisions)
Jump to: navigation, search
(Timeline View)
Line 206: Line 206:
 
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 [http://simile.mit.edu/timeline/ 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:  
 
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 [http://simile.mit.edu/timeline/ 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:  
  
  <nowiki><script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/extensions/time/time-extension.js" type="text/javascript"></script></nowiki>
+
  <nowiki>
 +
<script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/extensions/time/time-extension.js"  
 +
type="text/javascript"></script></nowiki>
  
 
Then add this view after the Thumbnail view code block:  
 
Then add this view after the Thumbnail view code block:  
Line 226: Line 228:
 
  </div></nowiki>
 
  </div></nowiki>
  
Save and reload in the browser. That's it!  
+
Save and reload in the browser. That's it!
  
 
=== Exhibit Timeline View ===
 
=== Exhibit Timeline View ===

Revision as of 20:43, 17 February 2012

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/

Contents

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

Here is the whole HTML file for this tutorial:

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

    <link href="nobelists.js" type="application/json" rel="exhibit-data" />
<script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/exhibit-api.js"></script>
    <script src="http://api.simile-widgets.org/exhibit/3.0.0rc1/extensions/time/time-extension.js?bundle=false"></script>    
    <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>
    <script type="text/javascript">
        function deceaseRowStyler(itemID, database, tr, rowIndex) {
            var deceased = database.getObject(itemID, "deceased");
            if (deceased == "yes") {
                tr.style.backgroundColor = "#f88";
            }
        }
    </script>
  </head> 
  <body>
    <div id="main-content">
        <div id="title-panel">
          <h1>63 MIT-related Nobel Prize Winners</h1>
          <p>The information within this page has been retrieved from
          <a href="http://web.mit.edu/newsoffice/special/nobels.html" target="_blank">this MIT official source</a> while the thumbnails are included from <a href="http://nobelprize.org/" target="_blank">Nobelprize.org</a>. Here is the <a href="nobelists.js" target="_blank">Exhibit JSON data file</a>.
          </p>
        </div>
    
        <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>
        <div ex:role="viewPanel" style="padding: 1em 0.5in;">
            <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>
        
            <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>
            <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>
            <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>
        </div>
    </div>
  </body>
</html>

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