I'm a data journalist working for The News Journal in Delaware.

You'll probably find a lot of stuff about journalism, data and data visualization (nerd alert) and other random musings.

All things
Patrick Sweet



HOW-TO: Using pop-ups to embed DocumentCloud notes

For a story that ran this past weekend, I was asked to figure out how we could incorporate notes created in DocumentCloud - a tool for journalists that is invaluable for organizing, annotating and publishing documents.

We had more than 15 highlights from roughly 175 pages of emails between developers and state officials regarding a riverfront project in Wilmington that we wanted to share within the text of the article online. DocumentCloud has some great publishing features that allow you to fill a div tag with a snippet of the document (along with a complete document viewer that we embedded on a separate page), but the text column on our website has varying widths because of sidebar content, so it would have been a bit ugly to place the snippets within the story. The workaround: Using qTip, a jQuery plugin, to turn the embedded document snippets into popups connected to links formatted like this:

 <a class="DCPopup" href="javascript:;" style="font-weight:bold" name="354770_56343">

This format was the same for every link, the only difference is in the “name” attribute, which stores the document id and note id separated by an underscore. The JavaScript looks for “a” tags with the “DCPopup” class and goes to work. Here’s the script that takes care of the entire thing:

    // Use each method to grab the DocumentCloud links.
        // Grab Document ID and Annotation ID from the 'name' attribute.
        var embedIDs = $(this).attr('name').split("_");
        var docID = embedIDs[0];
        var noteID = embedIDs[1];

        // Create the content using the qtip plugin.
            // Create content DIV with unique ID for each annotation.
            content: '<div id="DC-note-'+noteID+'" class="DC-note-container"></div>',
            position: {
                corner: {
                    tooltip: 'bottomMiddle', // ...and position it according to the tooptip.
                    target: 'topMiddle' // ...and position it according to the link location.
            show: {
                when: 'click', // Show it on click...
                solo: true // ...and hide all others when its shown
            hide: 'unfocus', // Hide it when inactive...
            style: {
                width: 700,
                height: 'auto',
                padding: 0,
                tip: 'bottomMiddle',
                name: 'light',
            api: { // This callback is what actually fills the div with the embedded note.
                onRender: function(){
        }).attr('href', 'javascript:;'); // This stops the browser from changing the url.

Pretty simple, right? qTip handles all the heavy lifting, and the only thing that might throw people off is the “api: ” portion of the script, which is just a callback that is triggered when the popup loads. If you check out qTip’s documentation, there’s a great demo on how to use this feature to load Youtube videos. In this case, we are using the exact same function that is provided when you click “Embed a note” in DocumentCloud to load the content. Nothing fancy and it works great.

The only other thing you have to do to make the whole thing work is make sure jQuery, qTip and DocumentCloud’s loading script are loaded on the page. Be careful, though, to make sure they are in the right order. You have to load jQuery first, followed by qTip and DocumentCloud before the custom script. In our case, I stored the above script in a separate .js file and included all of them at the end of the story. The final paragraph in our CMS (Saxotech), looked like this:

<script type="text/javascript" src="PATH-TO-jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="PATH-TO-jquery.qtip-1.0.0-rc3.min.js"></script>
<script src=''></script>
<script type="text/javascript" src="PATH-TO-THE-SCRIPT-ABOVE-dcembed-popup.js"></script>

That’s all there is to it. Hopefully someone will find this helpful. If you have any feedback, suggestions or ideas to better incorporate this type of content into a page, please share it in the comments.

  1. patricksweet posted this
blog comments powered by Disqus