Dug.js — A JSONP to HTML Script

Dug.js — A JSONP to HTML Script

So you want to display your Dribbble shots, recent pins on Pinterest, 500px or Instagram photos, Github commits, or recently listened to music on your blog or site? Then this chunk of javascript is for you. It was designed to be a lightweight, simple, library-independent script to pull in feeds of content available on the web as JSONP (there's lots of em!) to display on your site.

I wrote this script because I wanted a dead-simple way to show my dribbble shots on my site. I wanted to be able to customize the markup with a custom template and have the content client side cache. I wanted to do the same with Pinterest inspiration that I was finding for illustrations that I love. Instead of having dedicated scripts for every service, why not just have one very small raw script (~200 lines) to do it all?

Dug.js Setup

Enough windbaggery, let me show you how to use it. Because Dug.js is on my site, I can run the code in this blog post. Let's talk about that Dribbble implementation first. So, I want to pull in my latest Dribbble shots. Scanning the Dribbble api, I see that they do support JSONP and that you can pull in all player shots with the following url: http://api.dribbble.com/players/:id/shots

Rad! With Dug.js, we're nearly there. In it's simplest form, you really only need two things.

  1. An api endpoint (jsonp callbacks supported)
  2. An HTML template to display the data

With that in mind, let's setup dug.js to pull dribbble shots from an awesome illustrator's account:

<script>
  dug({
      endpoint: 'http://api.dribbble.com/players/justinmezzell/shots',
      template: '{{#shots}}<img src="{{image_400_url}}">{{/shots}}'
  });
</script>

If you're familiar with mustache or similar templating, the {{#shots}}...{{/shots}} section apply the html within it over every shot, in this case, emitting an image for each shot. Hint: you can also supply a CSS selector to target a template script, and Dug.js will pull the content from it.

That's a pretty simple example, but what if you want each shot linking to it's detail page? Here ya go:

<script>
  dug({
      endpoint: 'http://api.dribbble.com/players/justinmezzell/shots',
      template: '<ul>\
          {{#shots}}\
            <li>\
                <a href="{{url}}" title="{{title}}">\
                    <img src="{{image_400_url}}" alt="Image of {{title}}">\
                </a>\
            </li>\
        {{/shots}}\
      </ul>'
  });
</script>

Here's an actual demo of the above code, running:

That's it! Pretty simple huh? Yeah, thats why I dig it too!

Dug.js Parameters

For those that are curious, here's a few parameters (as json name-value pairs) that you can pass into dug to do some additional schnazzy things:

  • target — the id of an existing DOM element to put the html results in.
  • cacheExpire — # of milliseconds to cache data on the client side (using localstorage). 0 for no caching.
  • callbackParam — the name of the query variable a JSONP service will use for a callback function. Most services just use 'callback=functionName', but sometimes a service will use a different query variable name.
  • success — a function to call when JSONP data is successfully retrieved.
  • error — a function to call when JSONP data is not successfully retrieved.
  • beforeRender @param data — a function called before Dug.js renders the template. Helpful for trimming/changing the data before it renders.
  • afterRender @param data — a function called after Dug.js renders the template.

Download Dug.js

Dug.js is completely free! Although, if you're diggin' this script hard and want to help fund my graphic tablet purchase (for art like Dug the dog above. Yay!), feel free to donate.

Download Dug.js

License

Dug.js is 100% free under the WTFPL — no link backs or anything needed.

javascript plugin freebie