11.2. Case Study: mod_BookMy wife and I recently moved from London, England, to Florence, Italy, via Sweden. In the first edition of this book, we were just about to leave, and to that effect, much of the contents of our home was already in storage: most of it being books. In the end, it turned out we sent 86 tea chests full of books across Europe. So now we're unpacking. Many people really like our books and would like to borrow them, and so, for many reasons, it would be quite cool to list details of our books into a feed. As we unpack the books, we will most likely try to scan their barcodes and arrange our library (we're geeky like that), so we will have all sorts of data available. The challenge is then to design a module for both 1.0 and 2.0 (and Atom, eventually) that can deal with books. 11.2.1. What Do We Know?The first thing to think about is precisely what knowledge you already have about what you're trying to describe. With books, you know a great deal:
There are also, alas, things that you might think you know, but which, in fact, you don't. In the case of books, unless you are dealing with a specific edition in a specific place at a specific time, you don't know the number of pages, the price, the printer, the paper quality, or how critics received it. For the sake of sharable data, these aren't universally useful values. They will change with time and aren't internationally sharable. Remember that once it has left your machine, the data you createin this case, each itemis lost to you. As the first author, it is your responsibility to create it in such a way that it retains its value for as long as possible with as wide an audience as possible. So, Rule 1 of module design is: decide what data you know, and what data you do not know. 11.2.2. Can We Express This Data Already?Rule 2 of module design is: if possible, use another module's element to deliver the same information. This is another key point. It is much less work to leverage the efforts of others, and when many people have spent time introducing Dublin Core support to desktop readers, for example, you should reward them by using Dublin Core as much as possible. Module elements need to be created only if there is no suitable alternative already in the wild. So, to reexamine the data:
So, out of all the information we want to include, we need to invent only two new elements: book:isbn and book:openingPara. This isn't a bad thing: modules do not just consist of masses of new elements slung out into the public. They should also include guidance as to the proper usage of existing modules in the new context. Reuse and recycle as much as possible. To summarize, we now have: <title/> <dc:author/> <dc:publisher/> <book:isbn/> <dc:subject/> <dc:date/> <book:openingPara/> 11.2.3. Putting the New Elements to Work with RSS 2.0Before creating the feed item, let's decide on what the link will point to. Given that my book collection isn't web-addressable in that way, I'm going to point people to the relevant page on http://isbn.nu, Glenn Fleishman's book-price comparison site. For an RSS 2.0 item, you can therefore use Example 11-1. Example 11-1. mod_Book for RSS 2.0<item> <title>Down and Out in the Magic Kingdom</title> <link>http://isbn.nu/0765304368/</link> <dc:author>Cory Doctorow</dc:author> <dc:publisher>Tor Books</dc:publisher> <book:isbn>0765304368</book:isbn> <dc:subject>Fiction</dc:subject> <dc:date>2003-02-01T00:01+00:00</dc:date> <book:openingPara> I lived long enough to see the cure for death; to see the rise of the Bitchun Society, to learn ten languages; to compose three symphonies; to realize my boyhood dream of taking up residence in Disney World; to see the death of the workplace and of work.</book:openingPara> </item> As you can see in this simple strand of RSS 2.0, the inclusion of book metadata is easy. You know all about the book, and a mod_Book-compatible reader allows you to read the first paragraph and, if it's appealing, to click on the link and buy it. All is good. 11.2.4. Putting the New Elements to Work with RSS 1.0With RSS 1.0, let's make a few changes. First, the book needs a URI for the rdf:about attribute of item. This isn't as straightforward as you might think. You need to think about precisely what you're describing. In this case, the choice is between a specific bookthe one that is sitting on my desk right nowand the concept of that book, of which my specific book is one example. The URI determines this. If I make the URI http://www.benhammersley.com/myLibrary/catalogue/0765304368, the item refers to my own copy: one discreet object. If, however, I make the URI urn:isbn:0765304368, the item refers to the general concept of Cory Doctorow's book. For our purposes here, this is the one to go for. If I were producing an RSS feed for a lending library, it might be different. Example 11-2 makes these changes to mod_Book in RSS 1.0. Example 11-2. mod_Book in RSS 1.0<item rdf:about="urn:isbn:0765304368"> <title>Down and Out in the Magic Kingdom</title> <link>http://isbn.nu/0765304368/</link> <dc:author>Cory Doctorow</dc:author> <dc:publisher>Tor Books</dc:publisher> <book:isbn>0765304368</book:isbn> <dc:subject>Fiction</dc:subject> <dc:date>2003-02-01T00:01+00:00</dc:date> <book:openingPara> I lived long enough to see the cure for death; to see the rise of the Bitchun Society, to learn ten languages; to compose three symphonies; to realize my boyhood dream of taking up residence in Disney World; to see the death of the workplace and of work.</book:openingPara> </item> The second thing to think about is the preference for all the element values within RSS 1.0 to be rdf:resources and not literal strings. To this end, you need to assign URIs to each possible value. Within RSS 1.0, you can keep extending all the information you have to greater and greater detail. At this point, you must think about your audience. If you foresee people using the feed for only the simplest of taskssuch as displaying the list in a reader or on a siteyou can stop now. If you see people using the data in deeper, more interesting applications, then you need to give guidance as to how far each element should be extended. For the purposes of this chapter, we need to go no further, but for an example, let's go anyway. Example 11-3 expands the dc:author element via RDF and the use of a new RDF vocabulary: FOAF, or Friend of a Friend (see http://www.rdfweb.org). Example 11-3. Expanding the module even further<?xml version="1.0"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:book="http://www.exampleurl.com/namespaces" xmlns="http://purl.org/rss/1.0/" > <item rdf:about="urn:isbn:0765304368"> <title>Down and Out in the Magic Kingdom</title> <link>http://isbn.nu/0765304368/</link> <dc:author rdf:resource="mailto:doctorow@craphound.com" /> <dc:publisher>Tor Books</dc:publisher> <book:isbn>0765304368</book:isbn> <dc:subject>Fiction</dc:subject> <dc:date>2003-02-01T00:01+00:00</dc:date> <book:openingPara> I lived long enough to see the cure for death; to see the rise of the Bitchun Society, to learn ten languages; to compose three symphonies; to realize my boyhood dream of taking up residence in Disney World; to see the death of the workplace and of work.</book:openingPara> </item> <dc:author rdf:about="mailto:doctorow@craphound.com"> <foaf:Person> <foaf:name>Cory Doctorow</foaf:name> <foaf:title>Mr</foaf:title> <foaf:firstName>Cory</foaf:firstName> <foaf:surname>Doctorow</foaf:surname> <foaf:homepage rdf:resource="http://www.craphound.com"/> <foaf:workPlaceHomepage rdf:resource="http://www.eff.org/" /> </foaf:Person> </dc:author> </rdf:RDF> Because only you, as the module designer, know the scope of the data you want to put across, you must document your module accordingly. Speaking of which... 11.2.5. DocumentationYou must document your module. It is obligatory. The place to do so is at the address you use as the namespace URI. Without documentation, no one will know precisely what you mean, and no one will be able to support your module. Without support, the module is worthless on the wider stage. |