Upgrade StorageSharing PHP code for serving COinS metadata
Hello, everyone,
I have successfully created a site that serves up COinS metadata. The code (and COinS) aren't perfect, but I think it's worth sharing. I'd be interested to hear if anyone improves on this code. In fact, my code is almost exactly the same as offered on the Zotero COinS page (http://www.zotero.org/support/dev/making_coins), but I fixed a couple of bugs, expanded the list of possible documents, and shifted from an object model (which required that you define the necessary classes) to one based on nested arrays. Also, I created a page that used the library function to show how it works in action.
To see the page in action, go to:
http://www.kb-creative.net/sei/coins_test/
You can download the code (in a zip file) from that page. The page itself is pretty boring (so it should be easier to adapt to your own purposes). The exciting thing is the little folder icon in the address window, which means that Zotero recognizes it. If you hover over the folder you'll see that Zotero recognizes the COinS metadata.
In the course of working out how to serve up metadata, I think I learned a few things about COinS and unAPI that I'd like to share. If I've got this wrong, please, someone, correct me. Zotero prefers unAPI, and for good reason: you can provide pdfs, URIs, abstracts, and other information that COinS doesn't support. (Actually, COinS supports URIs, but I couldn't get Zotero to recognize them... so I might have done something wrong.) However, unAPI requires an unAPI-conforming server, and I could not figure out how to do that. The most practical suggestions for a server seemed to say that you should use refbase. Unfortunately, we have a custom database (because it holds a lot more than bibliographic data), and so that wasn't an option for me. If anyone knows how to serve up richer metadata from COinS (or how to make a server work well with unAPI), I'd be happy to hear it.
Best regards,
Eric
I have successfully created a site that serves up COinS metadata. The code (and COinS) aren't perfect, but I think it's worth sharing. I'd be interested to hear if anyone improves on this code. In fact, my code is almost exactly the same as offered on the Zotero COinS page (http://www.zotero.org/support/dev/making_coins), but I fixed a couple of bugs, expanded the list of possible documents, and shifted from an object model (which required that you define the necessary classes) to one based on nested arrays. Also, I created a page that used the library function to show how it works in action.
To see the page in action, go to:
http://www.kb-creative.net/sei/coins_test/
You can download the code (in a zip file) from that page. The page itself is pretty boring (so it should be easier to adapt to your own purposes). The exciting thing is the little folder icon in the address window, which means that Zotero recognizes it. If you hover over the folder you'll see that Zotero recognizes the COinS metadata.
In the course of working out how to serve up metadata, I think I learned a few things about COinS and unAPI that I'd like to share. If I've got this wrong, please, someone, correct me. Zotero prefers unAPI, and for good reason: you can provide pdfs, URIs, abstracts, and other information that COinS doesn't support. (Actually, COinS supports URIs, but I couldn't get Zotero to recognize them... so I might have done something wrong.) However, unAPI requires an unAPI-conforming server, and I could not figure out how to do that. The most practical suggestions for a server seemed to say that you should use refbase. Unfortunately, we have a custom database (because it holds a lot more than bibliographic data), and so that wasn't an option for me. If anyone knows how to serve up richer metadata from COinS (or how to make a server work well with unAPI), I'd be happy to hear it.
Best regards,
Eric
Have you seen the unAPI plugin for WordPress? That may provide some leads on how to serve unAPI metadata.
I haven't figured out how to do edited volumes, which is going to be a problem for some of our publications. Also problems with conference papers.
I'll check out the unAPI plugin code for WordPress and RDFa to see if they would be better options.
Thanks!
Thanks, bdarcus -- that link helps, and I'll take a closer look at it. Meanwhile, I've looked at unAPI. Some information:
For background, when I tried to understand unAPI from the very short description of the standard, and from examples on a page, it looked frustratingly like magic -- there's really almost nothing on the page itself. What you have is a single link element saying what server will process your requests, then an abbr element for each reference. But there is no metadata on the page. After reading up on it, I know understand the sequence. Here, as I understand it, is what happens:
a) An unAPI client recognizes the abbr element on your page as an unAPI reference
b) It contacts the server listed in the link element on your page that has the server URL, saying that it (the unAPI client) is interested in a reference, passing the id from the abbr element
c) The server responds with a short (and simple) XML document listing all of the formats the server is willing to supply that reference in (MODS, MARCXML, RIS, ...)
d) The unAPI client responds to the server asking it to please provide the metadata in the format of its choice
e) The server responds with a properly formatted file
I got this information from the nice write-up at http://www.ariadne.ac.uk/issue48/chudnov-et-al/ (scroll down a bit for the technical details). I got the reference to the write-up as well as some clarity on how to structure a php server script from the WordPress plugin page (http://lackoftalent.org/michael/blog/unapi-wordpress-plug-in/) and the plugin code.
So, to implement unAPI you need:
1. The link element (that must point to *your* server script, e.g., a php script)
2. An abbr element for each reference that provides an id that your server can recognize
3. Code to provide the XML that the unAPI client can parse to understand what formats are available
4. Code to format the metadata in the formats you provide.
So, in addition to unAPI, you *also* need to know about, say, MODS (http://www.loc.gov/standards/mods/mods-guidance.html), MARCXML (http://www.loc.gov/standards/marcxml/), RIS (http://www.refman.com/support/risformat_intro.asp), etc. The WordPress plugin serves up several formats, but it only uses a few of the available tags in each format, because it is only serving up metadata for blogs, not for books, journal articles, conference papers, etc.
This really looks like the way to go. Unfortunately, for now it is probably more than I have the time to do. I may change my mind later. But at the moment I'm doing the coding in my spare time because I'm advocating for making our document library Zotero-ready. So, for now, I'll stick with COinS which, despite its problems, only requires serving up metadata directly in the page. I'll also pass what I've found along to the main coder and see if he can make the time for it.
Next... I'll look at BIBO encoded as RDFa.
Another tip. Take a look at Zotero's code to see what format names it is expecting from unAPI sources:
https://www.zotero.org/trac/browser/extension/trunk/translators/unAPI.js
The list at present is:
var RECOGNIZABLE_FORMATS = ["mods", "marc", "endnote", "ris", "bibtex", "rdf"];
Eric
Thanks again for the tips. I took a look at BIBO RDFa, and it looks very interesting. Like other RDF and a lot of XML I've looked at, it's top-heavy, but it looks like a very complete specification (it even includes status info like "pending" and "rejected"), and also like other RDF & XML, it's not hard to automate the generation of the top-heavy text. Also, like COinS, it sits on the page, and doesn't require an associated server, as unAPI does. Because of financial and time limitations, for now, I'm going to have to stick with COinS -- hopefully to change in the future. Meanwhile, I can't decide between unAPI and BIBO RDFa as a future technology. So, for the present I'll just put down my thoughts about the three options.
COinS
- Simple to implement on the server and client end
- Sits within the page -- very few moving parts
- Extremely limited metadata format
BIBO RDFa
- Not too bad on the server end -- lots of text, but much of it "boilerplate", so not hard to automate
- Sits within the page
- Very flexible metadata format
- Might or might not be hard on client end -- need a suitable parser -- if client doesn't already have one, they have to write one
unAPI
- A bit of a chore to implement (but not too bad): need to put links in the page, also provide an unAPI server (which can be written in any server-side language you have available)
- If already serving up RIS, MODS, etc., can layer on top of existing technology
- Similarly, if a client is already parsing RIS, MODS, etc., can layer on top of existing technology -- and it is easy to do
- Completely flexible metadata format, because it doesn't pick one -- you say which ones you serve, and offer them
The most flexible of these from the client point of view is unAPI. Probably the simplest way to get feature-rich metadata on the page from a server point of view is BIBO RDFa. I don't know how to choose. But for now, I don't need to, since I can't implement it anyway. Over the next few months I'll be thinking about options. In the meantime, if anyone has any thoughts or comments about making sites Zotero-ready, please share!
Eric
Thanks