HTML5 Portfolio Project – Part 2

Jump to Part 1 here.

Today, we’re going to define the data format for our portfolio. Back in 2005, XML was the last data format we were ever going to need, so that’s what I used. It must have been second-to-last, because today, everyone seems to prefer JSON. I’m more than happy to commiserate about the pros and cons over beers sometime, but I’ve moved on. We’re doing this in JSON. Afterall, the portfolio is going to be driven by JavaScript; I doubt much justification is warranted.

Don Your Information Architect Hat

A portfolio is a list of projects. Each project has a bunch of properties like a title and a URL. Each project will also have some media (like pictures and/or video) and a brief, text-based description.

Here’s what I came up with originally:

• client – eg. Microsoft
• title – eg. Micro-site
• description – eg. “Lorem ipsum…”
• date – eg. January 2011
• role – eg. developer
• link – eg. http://microsoft.com/someMicroSite
• thumbnail – eg. thumbnails/3d-templates.jpg
• media – eg. microsite/image1.jpg, microsite/image2.jpg, microsite/image3.jpg, microsite/video.mov

All fairly straight-forward, I hope.

I did over-simplify the items in the media section. In order to make this work, we need to know a little more than just what URL has the media.

• title – eg. Image 1
• icon type – eg. pic / video
• content – eg. microsite/image1.jpg

Turning all of this into JSON should be easy. First, double-check to make sure our names make sense and are consistent. … Then, we need to decide whether it makes sense to encode items with more than one value as an Array or as an Object (hash). There are two spots in this project where this comes into play. One should be obvious. Can you spot the second?

1. The list of projects
2. The list of media belonging to each project

Above all else, it pays to be consistent. The two items above are similar enough that, whether we choose to store them in an Array or an Object, we’ll probably want to use the same approach for both.

Array is Best

You’ll want to use an Array when you have a list of things and their order matters. We want to display projects in a specific order, so let’s use an Array. That was easy! Wait…

No, Object is Best

You want to use an Object when you have a list of things and the order doesn’t necessarily matter, and each item can be identified by some sort of unique key. An Array (a type of Object afterall) often does this automatically. It uses numeric keys.

Come to think of it, each of our projects will be accessible via a unique URL. And, hey, the media items will have URLs as well. But wait, we didn’t show “url” anywhere in our list of properties. Where should it go? If I use an Object to store my list items, I could use the URL fragment as the key, or I could go back to the Array (preserving the order of my list) and add a “url” property to each item…

Just Pick One Already

Hopefully you’re starting to see that there’s no one right way to do this. I want to be able to control the order of my items, but I also need to access each item by a unique key (its URL). Here’s a sample of what I think my data will look like (so far).

[
  {
    "url"         : "contact",
    "client"      : "Email:<br />jon@shovemedia.com",
    "title"       : "contact info",
    "description" : "content/contact.html",
    "date"        : "01/01/2011",
    "role"        : "developer",
    "link"        : "mailto:jon@shovemedia.com?subject=New Business",
    "thumbnail"   : "thumbnails/email.jpg",
    "pics"        : []
  },
  {
    "url"         : "3D",
    "client"      : "Photobiz",
    "title"       : "3D Templates",
    "description" : "content/3d.html",
    "date"        : "01/01/2011",
    "role"        : "developer",
    "link"        : "http://photobiz.com",
    "thumbnail"   : "thumbnails/3d-templates.jpg",
    "pics"        : [
            {
              "url"     : "video",
              "title"   : "watch!",
              "icon"    : "video",
              "content" : "papervision/videoPlayer.html"
            },
            {
              "url"     : "image1",
              "title"   : "Image 1",
              "icon"    : "pic",
              "content" : "papervision/image1.jpg"
            }
          ]
  }
]

Most of this is identical to the XML format I’ve been using. I’ve introduced one small change for the “description” field. Rather than trying to embed HTML within a JSON document (and spending a tutorial or three to explain it), I’m going to place that in an external document and load it on request. That’s “lazy initialization” for the initiated.

Stay Tuned:

In the next episode, we’ll decide how best to organize everything into folders at the file system level. If you take a close look at the JSON above, you’ll should be able to spot a hint or two in some of the example values that contain file paths.