Creating COinS for websites

SimonCropper

I have been trying to incorporate some of my bibliography in my website using "ContextObject in Span" or COinS. I found useful information on the web about the standard (http://ocoins.info/) and even a number of COinS generators (http://generator.ocoins.info/).

The problem I had was that I wanted to export 10-20 references at a time and having to reenter data I already had on Zotero seemed a waste of time.

I searched the forums extensively but found no clear information on the ability to export COinS. The documentation does have a page pointing to a php script (http://www.zotero.org/support/dev/exposing_metadata/coins) but this required understanding how to integrate this with Zotero.

As it turns out, Zotero has the ability to export COinS already. It is just well hidden!

Select a number of references then right-click the selection. Choose "Create bibliography from Selected Item" -- select the Citation Style and save as HTML.

When viewing the HTML page created you will see your selected references in the Citation Style chosen. If you view the source code, you will see the COinS span class="Z3988" ...> construct and if you paid attention you will have seen that Zotero 'saw' the reference(s) and gave you the option in the address bar of importing the reference (or collection).

Hopefully this post will save others from spending days trying to figure out how to implement this functionality when it already exists!

P.S. For the developers: As well as making existing functionality better documented, it would be useful to have the ability to 'export' in COinS format to the clipboard or a text file, so a web developer can cut and paste references to webpages that have already been created.

mark

See also these old threads:
http://forums.zotero.org/discussion/10755/option-to-generate-coins-or-use-coins-without-the-presentational-markup/

http://forums.zotero.org/discussion/10838/no-editors-in-coins/

SimonCropper

Thanks Mark. I missed that feature request.

In regards to having extraneous lines of text in the HTML file I thought of filtering the text using python so I just had the 'COinS' lines being listed and capturing the standard output and plonking it into the clipboard.

If you saved to a standard output file name, the program could be run from a desktop shortcut. So... 1. Create bibliography, 2. Save to a standard name, 3. Run the python routine, 4. Ctrl-V to paste. What do you think? Still too long-winded, or worth the effort?

SimonCropper

Here is a simple method I worked out to get embedded COinS data from a HTML file created using Zotero. The following has been tested on Ubuntu 10.04 LTS (Linux).

The one-line-script assumes you always call your file the same name and save it in the same place.

Once you 'Create your bibliography' and save it as a HTML file, it is simply a matter of running the script. The COinS objects will be in your clipboard and you can use Ctrl-V to past them into any document.

Here are the step by step instructions on how to setup the script

STEP 1. Check you have xclip. Open a terminal and type 'xclip -h'. If it is installed it will print the help; if it is not type 'sudo apt-get install xclip' then hit 'enter'. This will install the program on your computer. 'xclip' is used to put data printed to the terminal into the system's clipboard.

STEP 2. Create a text file called 'get_coins.sh'. Make sure it is executable (see here for how to set the execute flag on a file).

STEP 3. Place the following code in the text file and save the file somewhere.


#!/bin/bash

# assume a standard place and name
grep Z3988 ~/Desktop/bib.html | xclip -selection clipboard



• #!/bin/bash just tells the scripting routine which package to use.


• grep Z3988 ~/Desktop/bib.html basically lists all the lines in 'bib.html' that contain 'Z38988'.


• | xclip -selection clipboard means pipe (or send) the data found by 'grep' and put it into the clipboard.

STEP 4. Create a desktop launcher and point it to the bash script you just created (see here on how to create a desktop launcher in Ubuntu).

The script is now setup so you can easily extract COinS data from the specified HTML file.

Here is how it would work on a day-to-day basis

STEP 1. Open Zotero and select those references you want to create COinS for insertion into a website.

STEP 2. Right-click the selection and choose 'Create bibliography from Selected Items'. Choose the 'Citation Style' and check 'Save as HTML. Click OK.

STEP 3. Save the file to the directory you specified in the bash script. For ease I specified the 'Desktop' and called the file 'bib.html'. For the moment do this but remember you can change this later.

STEP 4. Double click the desktop launcher you created earlier. Because we did not insert any feedback mechanism in the script it will just run. Open an editor and press 'Ctrl-V'. The data extracted from the 'bib.html' file should be in the clipboard.

STEP 5. Open a blog, webpage or any other HTML document and insert the COinS between the <body></body> tags. Save the HTML file and open it in a browser. You should see a Zotero book, article or collection icon in the address bar depending on how many and what type of COinS you inserted.

NOTE. As we are only inserting empty <span></span> tags (i.e. the COinS), no additional text will be visible in your webpage.

mark

Very nice, Simon! This looks like a workable solution for what I wanted.

ajlyon

I'm sorry I didn't chip in earlier, but this is much more easily accomplished by using a Zotero export translator. I added export capabilities to the existing COinS translator -- just a couple of lines, since the COinS functionality is built in to Zotero. Go to http://github.com/ajlyon/translators/raw/master/COinS.js and save the file to the translators directory of your Zotero data directory (http://www.zotero.org/support/zotero_data). Then restart Zotero and you should now be able to select COinS as an export format. The export will consist of lines like:

<span class='Z3988' title='..'></span>
<span class='Z3988' title='..'></span>
<span class='Z3988' title='..'></span>

You can use this in conjunction with the Quick Copy settings in the preferences to drag-and-drop COinS onto specified sites, or to make this your preferred output format for drag-and-drop in general.

This hasn't been tested, so let me know how it goes for you.

SimonCropper

ajlyon,

I tried what you said and found that the export option did not work. Although the option appeared, when I tried to save, it crashed (error: "newItem is not defined". The export file was empty.

The other point worth mentioning is that the data, if successfully exported still needs to be imported into a webpage. The number of steps involved is still about the same. Why can't you send the data to the clipboard and the export file.

What is needed is the ability to export to the clipboard so you can dump it to a file.

ajlyon

Install and restart again-- I had overlooked a variable rename at the last moment.

You can set Zotero to use an export translator for Quick Copy, in the preferences, so you don't have to open the file that the export creates.

SimonCropper

OK that worked. Any chance of inserting a dialog asking if the user wants the data copied to the clipboard, then doing it?

ajlyon

Nope, since translators aren't supposed to do things like that (and don't have direct access to the clipboard).

This is a general limitation of Zotero's export function. There should be an option in general to put the exported metadata on the clipboard, just like there is for generated bibliographies.

SimonCropper

OK. Do you know any of the developers that could implement this feature? I presume it would be relatively easy, yet be very helpful for a wide variety of users.

ajlyon

I've added a ticket: https://www.zotero.org/trac/ticket/1885

I don't know if anyone will take this up, but it shouldn't be hard at all. In the meantime, I'll push the modified COinS to the main repository, since I think the export function might find more general use.

nschneid

Thanks @ajlyon—cf. http://forums.zotero.org/discussion/510/export-to-clipboard-instead-of-file/ (also about clipboard export functionality).

SimonCropper

For clarity I have outlined what the preceding post alludes.

If you open your preference dialogue (Action > Preferences), then select the 'Export' tab, you have the ability to define a quick copy format. Select COinS, then exit.

Now from the normal library pane you can select various references and (1) drag these to a page, or (2) Ctrl-Shift-C or Ctrl-Alt-C to put in the clipboard for pasting into whatever you want. The references are copied in COinS format. I have tested this on Ubuntu 10.04 LTS and it works well.

So as I said in the very first post to this thread -- As it turns out, Zotero has the ability to export COinS already. It is just well hidden!

adamsmith

This should really be documented on the "Exposing Metadata" site -
http://www.zotero.org/support/dev/exposing_metadata
SimonCropper - that site is a wiki, you should feel free to get an account
http://www.zotero.org/support/dev/documentation
and update the info on COinS

SimonCropper

Adam,

Thanks for the post. I have discovered that the COinS created using this method are not the same as those created by the method described above by me.

In fact these COinS are not formatted correctly and do not get picked up by Zotero.

The problem is the spans are incorrectly formatted. Here are the issues...

1. ampersands are represented as '&' not '& a m p ;'
2. rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook or ...journal not present in title attribute.
3. the metadata is not preceded by 'rft.' For example btitle=Blah%20Blah should be rft.btitle=Blah%20Blah

It is only after all these changes are made that Zotero sees and can import the data. The only other format difference is that the incorrect version using single quotes rather than double-quotes, but this does not seem to matter.

dstillman

I have created a wiki page outlining this feature

Thanks for writing this up. This should go in the dev section of the wiki, though, and it should be a COinS-specific page (e.g., /support/dev/coins and with an appropriate title). Zotero supports many metadata formats, and there's already a general page on Exposing Metadata, which adamsmith linked to above.

SimonCropper

Hi Dan,

Aside from the fact that the procedure does not work, which I presume eventually will be fixed. This task is a user task not a developer task.

As this post attests (and the numerous cross-links by different contributors, and links in their posts that go around and around) this action - "shoving your references into a blog so others can import them into their library" is considered by most to be a task everyday users do, not developers.

I disagree that it should be buried in the developers section.

dstillman

You used the word "developer" on the page itself and in your first post in this thread. The "Exposing Metadata" page—which this page should be linked from—is in the dev section, and it lists "blogger" as an example of its intended audience. The dev section is where we put this kind of information. It seems redundant to have two separate pages on COinS, even if they've been written for somewhat different audiences. If you think the existing one is too complicated, edit it, and create separate sections for the different methods. Rintze, who I believe wrote that page, may want to weigh in, but most of the info on there seems unnecessary and best served by a link to ocoins.info.

And COinS is still only one of a number of ways to embed metadata, so the page you wrote should be renamed one way or another.

SimonCropper

I am happy to acquiesce, please refer me to some documentation on how to move or delete a wiki page. The wiki only states that it can be done but provides no information on how to do it.

At the moment I am considering removing the wiki page. The reason is that the procedure does not work. I have made a copy for my records and will repost once the bug is fixed but think that it will just confuse matters if left floating around. I have made some edits to the wiki page indicating what the problem is but also consider this is probably is not a good look.

adamsmith

I've added the fact that html bibliographies created by Zotero contain COinS to the exposing metadata site.

I wouldn't pay much attention to the section of the website this is getting put in - Dan is right, that given the structure of the existing documentation it makes much more sense to put it in the dev section, but what really matters is where it is linked to from (and the exposing metadata page is clearly the right place for that) and that people searching the support or just using google are going to find it.

So yes, do edit the existing /dev/.../coins page an add your information as soon as this actually works.

SimonCropper

I have removed direct links to the wiki page from the above thread.

I have removed all text from the wiki. If shown how, or if someone wants to do it on my behalf, I will remove the empty wiki page.

dstillman

I've removed it. Thanks.

Rintze

Rintze, who I believe wrote that page, may want to weigh in

I probably just moved it.

ajlyon

In fact these COinS are not formatted correctly and do not get picked up by Zotero.

The problem is the spans are incorrectly formatted. Here are the issues...

1. ampersands are represented as '&' not '& a m p ;'
2. rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook or ...journal not present in title attribute.
3. the metadata is not preceded by 'rft.' For example btitle=Blah%20Blah should be rft.btitle=Blah%20Blah

I'm just blindly wrapping the output of Zotero's createContextObject, which I expected to work correctly, and which presumably underlies the feature in exported bibliographies. Perhaps Dan or Simon can comment on why the output is different, or I can go code diving and see what I dig up.

SimonCropper

Sorry to me the output appears to be created by different routines. Unless createContextObject has parameters that you did not specify I am sorry to say you will need to go diving.

ajlyon

Apparently Zotero defaults to generating COinS using OpenURL 0.1, rather than OpenURL 1.0. I've updated the translator to provide the proper parameters and generate correct COinS. Try downloading again from http://github.com/ajlyon/translators/raw/master/COinS.js and save the file to the translators directory of your Zotero data directory (http://www.zotero.org/support/zotero_data).

Restart Firefox and it should start working.

SimonCropper

First up. That worked.

Second. When you look at the export to HTML option in /zotero.jar/content/zotero/zpcom/cite.js (lines 336+) you can see that they call Zotero.OpenURL.createContextObject(Zotero.Items.get(itemID), "1.0"), which returns a string formatted with double-quotes not single quotes. I notice they also replace the amphersand, < and > symbols with '& a m p ;', '& l t' and '& g t ;' respectively (ignore spaces as they just prevent the forum software converting to &, < and >).

I have changed your doExport() function to reflect this code.

function doExport() {
var item;
var itemcoin;
var co;

while (item = Zotero.nextItem()) {
co = Zotero.Utilities.createContextObject(item, "1.0");

// Note the .replace functions should all be on the same line;
// they have been wrapped in this way for presentation.
// Note also the '& a m p ;' should not have spaces. As the
// forum 'sees these' as code and they are difficult to
// represent them in posts.
itemcoin= '<span class="Z3988" title="' +
co.replace("&", "& a m p;", "g")...
.replace("<", "& l t;", "g")...
.replace(">", "& g t;", "g") +
'"/>\n';
Zotero.write(itemcoin);
}
}

The result is that the COinS translator works and formatted strings created are comparable to the 'Create Bibliography' option.

I presume that anyone implementing this solution would require your COinS.jar file, so I will point them to this in the tutorial.

I will post a link to the tutorial when it is updated.

adamsmith

note that the new COinS.js file will likely be included in forthcoming Zotero updates.

dstillman

Yes, there's no need for people to install this manually. Just wait until this is in to document it.

And I don't know anything about the details here, but if this needs HTML escaping it should use Zotero.Utilities.htmlSpecialChars(str).

ajlyon

Escaping added, updated on Github.