| Next revision | Previous revisionLast revisionBoth sides next revision |
| dev:exposing_metadata:coins [2011/04/15 13:15] – created rmzelle | dev:exposing_metadata:coins [2017/11/12 19:53] – external edit 127.0.0.1 |
|---|
| ====== OpenURL COinS ====== | <html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">We’re |
| | in the process of updating the documentation for |
| | <a href="https://www.zotero.org/blog/zotero-5-0">Zotero 5.0</a>. Some documentation |
| | may be outdated in the meantime. Thanks for your understanding.</p></html> |
| |
| ===== What OpenURL is ===== | |
| |
| An OpenURL is a specially formatted URL containing bibliographic information. It allows you to link to a specialized search engine, called a resolver, at a library. The resolver gathers information from the OpenURL, then searches the library's resources to find out whether or not the library has a copy of that document available. The resolver, which is most commonly provided by [[http://www.exlibrisgroup.com/sfx.htm|Ex Libris' SFX]] software, searches not just the catalog, but also the library's proprietary database subscriptions. Then it presents the user with the results: | ====== Using Zotero to create COinS so you can embed metadata in your website ====== |
| |
| * If the document is available electronically, they get a link. | |
| * If the document is available in the stacks, they get a call number. | |
| * If the document is not available, they get a "sorry" message and maybe a link to Inter-Library Loan services. | |
| |
| OpenURL is also known as Z39.88 after the name of [[http://www.niso.org/kst/reports/standards?step=2&gid=&project_key=d5320409c5160be4697dc046613f71b9a773cd9e | ===== Introduction ===== |
| |the formal standard]] established by the National Information Standards Organization. | |
| |
| OpenURL systems are fairly expensive to create and maintain, and so they are not very widespread yet. Many universities have them, and a few large public libraries. | At times users wish to make references they have collated available to others when they visit their website or blog. This can be done by incorporating special code, called COinS, in your webpage. When COinS are detected by Zotero a book, chapter, article or collection icon appears in the address bar of the browser. Just as normal, users can click on the icon to capture the reference data and place it in their reference library. |
| |
| ===== What COinS are ===== | ===== What are COinS? ===== |
| |
| "COinS" stands for "ContextObject in Span." "ContextObject" is OpenURL jargon for the part of an OpenURL carrying the bibliographic information - basically, it's a query string, everything that would follow the ? in a regular URL. And "span" refers here to the HTML tag <span>. It's the ContextObject that carries the bibliographic information. | COinS is an abbreviation for "[[http://ocoins.info/|ContextObjects in Spans]]". Spans in this context refers to the html tag <span></span>, and is the means by which your reference data can be inserted into a webpage without it being rendered as text (i.e. it is hidden). |
| |
| The ContextObject is very flexible, and can carry everything from a simple title and author to more obscure things like a Serial Item and Contribution Identifier (SICI). | Although the format of COinS is relatively simple, their creation is problematic as it is necessary to convert certain characters to URL format. For example a blank character or space needs to be represented by '%20'. This makes reading and editing COinS difficult, although not impossible, for website developers. |
| |
| The upshot of which is that if you stick COinS in your web page, Zotero can pull all that data out again. | ===== How to create COinS ===== |
| |
| ===== Constructing COinS ===== | Zotero provides a simple means of creating COinS from the references in your library. |
| |
| The basic structure of a COinS reference consists of a span tag of the class "Z3988" and a title attribute with the ContextObject in it. Here's what a simple one looks like: | First, you need to set your 'Quick Copy' preferences. This is done by opening your Zotero Preference dialog using the menu option - 'Actions > Preferences...' then selecting the 'Export' tag (#1) and changing the 'Default Output Format' to COinS (#2). Close the dialog to return to your library. |
| |
| <span class="Z3988" title="__**ContextObject goes here**__"></span> | {{ :zotero_001.png?317x327 }} |
| |
| Let's look at the ContextObject: | Once you are back in your library select a reference or a collection of references and drag-and-drop them into a receptive application (e.g. text editor). The references are converted and inserted as a COinS object. |
| |
| - **ctx_ver=Z39.88-2004** specifies the version of the OpenURL standard we're using. | For example, below I have selected three references from my main library (#1). Then using the mouse, clicked on the selection and without releasing the button dragged the selection (#2) to gEdit, a text editor used in Ubuntu. Alternatively you can use Ctrl-Shift-C (Windows/Linux) or Cmd-Shift-C (Mac) to copy and Ctrl-V(Mac: Cmd-V to paste in a document. |
| - **&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook** says that the document is a book. | |
| - **&rft.btitle=The+Wind+in+the+Willows** is the title of the book. | |
| - **&rft.au=Grahame,+Kenneth** is the author of the book. | |
| |
| Putting all of those values on one line in the title attribute makes it a COinS reference. Here's a complete version: | {{ :zotero_002.png?489x106 }} |
| |
| <code><span class="Z3988" title="ctx_ver=Z39.88-2004&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.btitle=The+Wind+in+the+Willows&rft.au=Grahame,+Kenneth"></span> | The resulting output in gEdit is shown below. You can see what I mean about being difficult to read. |
| </code> | |
| |
| Apologies for the sideways scrolling. | ---- |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Thelymitra%20epipactoides%20F.%20Muell.%20(Orchidaceae)%3A%20The%20morphology%2C%20biology%20and%20conservation%20of%20an%20endangered%20species&rft.jtitle=Proceedings%20of%20the%20Royal%20Society%20of%20Victoria&rft.volume=101&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20M.%20Calder&rft.au=D.%20Tonkinson&rft.date=1989&rft.pages=89-101&rft.spage=89&rft.epage=101'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%207306%202243%206&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=A%20census%20of%20Victorian%20bryophytes&rft.place=East%20Melbourne&rft.publisher=The%20Department%20of%20Conservation%20and%20Environment&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20A.%20Tonkinson&rft.au=G.%20A.%20M.%20Scott&rft.date=1991&rft.tpages=56&rft.isbn=0%207306%202243%206'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%20643%2005533%209&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=Management%20of%20endangered%20plants&rft.place=East%20Melbourne&rft.publisher=CSIRO%20Publishing&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.date=1993&rft.tpages=182&rft.isbn=0%20643%2005533%209'></span> |
| | ---- |
| |
| There are a great many different fields you can use in COinS references. For a more complete reference, please see [[http://ocoins.info/|OpenURL COinS: A Convention to Embed Bibliographic Metadata in HTML]], especially the two "brief guide" sections listed in the table of contents. | Here is a formatted version, with some syntax highlighting, that you can more easily review. Note however, even with syntax highlighting the title attribute is just one continuous text string. |
| |
| ===== Appendix: a PHP function for making COinS ===== | <code html> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Thelymitra%20epipactoides%20F.%20Muell.%20(Orchidaceae)%3A%20The%20morphology%2C%20biology%20and%20conservation%20of%20an%20endangered%20species&rft.jtitle=Proceedings%20of%20the%20Royal%20Society%20of%20Victoria&rft.volume=101&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20M.%20Calder&rft.au=D.%20Tonkinson&rft.date=1989&rft.pages=89-101&rft.spage=89&rft.epage=101'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%207306%202243%206&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=A%20census%20of%20Victorian%20bryophytes&rft.place=East%20Melbourne&rft.publisher=The%20Department%20of%20Conservation%20and%20Environment&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20A.%20Tonkinson&rft.au=G.%20A.%20M.%20Scott&rft.date=1991&rft.tpages=56&rft.isbn=0%207306%202243%206'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%20643%2005533%209&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=Management%20of%20endangered%20plants&rft.place=East%20Melbourne&rft.publisher=CSIRO%20Publishing&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.date=1993&rft.tpages=182&rft.isbn=0%20643%2005533%209'></span> |
| | </code> |
| |
| Here is a brief function I worked out for making COinS references. I hereby consign it to the public domain - take it, use it, modify it, print it out and sleep on it, whatever. Read the comments before the function begins for complete documentation. You'll need to modify it to suit your own project. | The references copied are shown below. The COinS for these references have been inserted in the html of this webpage and should appear as a collection in the address bar of your browser (see image below and your browser's address bar). |
| |
| <code php><?php | |
| /* | |
| OpenURL() constructs an NISO Z39.88 compliant ContextObject for use in OpenURL links and COinS. It returns | |
| the proper query string, which you must embed in a <span></span> thus: | |
| |
| <span class="Z3988" title="<?php print OpenURL($Document, $People) ?>">Content of your choice goes here</span> | {{:dev:exposing_metadata:zotero_003.png|}} |
| |
| This span will work with Zotero. You can also use the output of OpenURL() to link to your library's OpenURL resolver, thus: | |
| |
| <a href="http://www.lib.utexas.edu:9003/sfx_local?<?php print OpenURL($Document, $People); ?>" title="Search for a copy of this document in UT's libraries">Find it at UT!</a> | Cropper, S.C., Calder, D.M. & Tonkinson, D. (1989) Thelymitra epipactoides F. Muell. (Orchidaceae): The morphology, biology and conservation of an endangered species. Proceedings of the Royal Society of Victoria 101: 89-101. |
| |
| Replace "http://www.lib.utexas.edu:9003/sfx_local?" with the correct resolver for your library. | Cropper, S.C., Tonkinson, D.A. & Scott, G.A.M. (1991) “A census of Victorian bryophytes” (The Department of Conservation and Environment; East Melbourne). |
| |
| OpenURL() takes two arguments. | Cropper, S.C. (1993) “Management of endangered plants” (CSIRO Publishing; East Melbourne). |
| |
| $Document - a document object, having an array (fields) with the following properties: | |
| $Document->fields["DocType"] | |
| 1 = Article | |
| 2 = Book Item (e.g. a chapter, section, etc) | |
| 3 = Book | |
| 4 = Unpublished MA thesis | |
| 5 = Unpublished PhD thesis | |
| |
| $Document->fields["DocTitle"] - Title of the document. | <html> |
| $Document->fields["JournalTitle"] - Title of the journal/magazine the article was published in, or false if this is not an article. | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Thelymitra%20epipactoides%20F.%20Muell.%20(Orchidaceae)%3A%20The%20morphology%2C%20biology%20and%20conservation%20of%20an%20endangered%20species&rft.jtitle=Proceedings%20of%20the%20Royal%20Society%20of%20Victoria&rft.volume=101&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20M.%20Calder&rft.au=D.%20Tonkinson&rft.date=1989&rft.pages=89-101&rft.spage=89&rft.epage=101'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%207306%202243%206&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=A%20census%20of%20Victorian%20bryophytes&rft.place=East%20Melbourne&rft.publisher=The%20Department%20of%20Conservation%20and%20Environment&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.au=D.%20A.%20Tonkinson&rft.au=G.%20A.%20M.%20Scott&rft.date=1991&rft.tpages=56&rft.isbn=0%207306%202243%206'></span> |
| | <span class='Z3988' title='url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=urn%3Aisbn%3A0%20643%2005533%209&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook&rft.genre=book&rft.btitle=Management%20of%20endangered%20plants&rft.place=East%20Melbourne&rft.publisher=CSIRO%20Publishing&rft.aufirst=S.%20C.&rft.aulast=Cropper&rft.au=S.%20C.%20Cropper&rft.date=1993&rft.tpages=182&rft.isbn=0%20643%2005533%209'></span> |
| | </html> |
| |
| $Document->fields["BookTitle"] - Title of the book in which this item was published, or false if this is not a book item. | {{tag>kb}} |
| | |
| $Document->fields["Volume"] - The volume of the journal this article was published in as an integer, or false if this is not an article. Optional. | |
| $Document->fields["JournalIssue"] - The issue of the journal this article was published in as an integer, or false if this is not an article. Optional. | |
| $Document->fields["JournalSeason"] Optional. | |
| The season of the journal this article was published in, as a string, where: | |
| Spring | |
| Summer | |
| Fall | |
| Winter | |
| false = not applicable | |
| $Document->fields["JournalQuarter"] - The quarter of the journal this article was published in as an integer between 1 and 4, or false. Optional. | |
| $Document->fields["ISSN"] - The volume of the journal this article was published in, or false. Optional. | |
| | |
| | |
| $Document->fields["BookPublisher"] - The publisher of the book, or false. Optional. | |
| $Document->fields["PubPlace"] - The publication place, or false. Optional. | |
| $Document->fields["ISBN"] - The ISBN of the book. Optional but highly recommended. | |
| | |
| $Document->fields["StartPage"] - Start page for the article or item, or false if this is a complete book. | |
| $Document->fields["EndPage"] - End page for the article or item, or false if this is a complete book. | |
| | |
| $Document->fields["DocYear"] - The year in which this document was published. | |
| | |
| $People - An array of person objects, each having an array, fields, with these properties: | |
| $People->fields["DocRelationship"] | |
| An integer indicating what kind of relationship the person has to this document. | |
| 0 = author | |
| 1 = editor | |
| 2 = translator | |
| $People->fields["FirstName"] - The person's first name. | |
| $People->fields["LastName"] - The person's last name. | |
| */ | |
| function OpenURL($Document, $People){ | |
| $DocType = $Document->fields["DocType"]; | |
| if($DocType > 2){ return false; } | |
| | |
| // Base of the OpenURL specifying which version of the standard we're using. | |
| $URL = "ctx_ver=Z39.88-2004"; | |
| | |
| // Metadata format - e.g. article or book. | |
| if($DocType == 0){ $URL .= "&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal"; } | |
| if($DocType > 0){ $URL .= "&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook"; } | |
| | |
| // An ID for your application. Replace yoursite.com and specify a name for your application. | |
| $URL .= "&rfr_id=info%3Asid%2Fyoursite.com%3AYour+Name+Here+Using+Plus+Signs+For+Spaces"; | |
| | |
| // Document Genre | |
| if($DocType == 0){ $URL .= "&rft.genre=article"; } | |
| if($DocType == 1){ $URL .= "&rft.genre=bookitem"; } | |
| if($DocType == 2){ $URL .= "&rft.genre=book"; } | |
| | |
| // Document Title | |
| if($DocType < 2){ $URL .= "&rft.atitle=".urlencode($Document->fields["DocTitle"]); } | |
| if($DocType == 2){ $URL .= "&rft.btitle=".urlencode($Document->fields["DocTitle"]); } | |
| | |
| // Publication Title | |
| if($DocType == 0){ $URL .= "&rft.jtitle=".urlencode($Document->fields["JournalTitle"]); } | |
| if($DocType == 1){ $URL .= "&rft.btitle=".urlencode($Document->fields["BookTitle"]); } | |
| | |
| // Volume, Issue, Season, Quarter, and ISSN (for journals) | |
| if($DocType == 0){ | |
| if($Document->fields["Volume"]){ $URL .= "&rft.volume=".urlencode($Document->fields["Volume"]); } | |
| if($Document->fields["JournalIssue"]){ $URL .= "&rft.issue=".urlencode($Document->fields["JournalIssue"]); } | |
| if($Document->fields["JournalSeason"]){ $URL .= "&rft.ssn=".urlencode($Document->fields["JournalSeason"]); } | |
| if($Document->fields["JournalQuarter"]){ $URL .= "&rft.quarter=".urlencode($Document->fields["JournalQuarter"]); } | |
| if($Document->fields["JournalQuarter"]){ $URL .= "&rft.quarter=".urlencode($Document->fields["ISSN"]); } | |
| } | |
| | |
| // Publisher, Publication Place, and ISBN (for books) | |
| if($DocType > 0){ | |
| $URL .= "&rft.pub=".urlencode($Document->fields["BookPublisher"]); | |
| $URL .= "&rft.place=".urlencode($Document->fields["PubPlace"]); | |
| $URL .= "&rft.isbn=".urlencode($Document->fields["ISBN"]); | |
| } | |
| | |
| // Start page and end page (for journals and book articles) | |
| if($DocType < 2){ | |
| $URL .= "&rft.spage=".urlencode($Document->fields["StartPage"]); | |
| $URL .= "&rft.epage=".urlencode($Document->fields["EndPage"]); | |
| } | |
| | |
| // Publication year. | |
| $URL .= "&rft.date=".$Document->fields["DocYear"]; | |
| | |
| // Authors | |
| $i = 0; | |
| while($People[$i]){ | |
| if($People[$i]->fields["DocRelationship"] == 0){ | |
| $URL .= "&rft.au=".urlencode($People[$i]->fields["LastName"]).",+".urlencode($People[$i]->fields["FirstName"]); | |
| } | |
| $i++; | |
| } | |
| | |
| return $URL; | |
| } | |
| ?> | |
| | |
| </code> | |
Upgrade Storage