Tumblr Kit

A jQuery framework for ajax loading post content via Tumblr’s v2 API and rendering it in your document using customisable JsRender templates. Requires a Tumblr OAuth Consumer Key. See the demo.

Dependencies

Tumblr Kit requires jQuery 1.5+ and JsRender 1.0pre+.

Setup

Include the dependent frameworks listed above:

	<script src="http://code.jquery.com/jquery.js"></script>
	<script src="http://borismoore.github.com/jsrender/jsrender.js"></script>

Declare global variables for your Tumblr OAuth Consumer Key (register one here) and your blog’s hostname:

	<script>
		var TUMBLR_API_KEY = "U41Qn………0e6aR";
		var TUMBLR_HOSTNAME = "matthewb.tumblr.com";
	</script>

Replace the values above with your own credentials.

If you’re including Tumblr Kit in a public theme, you’ll need to have your users generate their own key, which isn’t ideal. I believe Tumblr is looking at a solution to make this easier for theme authors, but for now you’ll need to provide a custom text tag for the Consumer Key and output the blog’s hostname using the undocumented {Host} tag:

	<meta name="text:Tumblr OAuth Consumer Key" content=""/>

	var TUMBLR_API_KEY = "{text:Tumblr OAuth Consumer Key}";
	var TUMBLR_HOSTNAME = "{Host}";

Post templates

Tumblr Kit uses JsRender templates to define the markup for each imported post. JsRender supercedes the now-deprecated jQuery Templates plugin. Boris Moore provides basic demos and documentation for JsRender, and I’ve put together a sample template for each post type as part of this repository.

Include a JsRender template in your HTML page for each post type you intend to import. For example, the template for a text post might look like this:

	<script id="tmpl-text" type="text/x-jsrender">
		<article id="post-{{:id}}" class="post-{{:type}}">
			<h1>{{:title}}</h1>
			{{:body}}
		</article>
	</script>

Tumblr’s API documentation provides a JSON schema for each post type that will help you to define your templates.

Note: you’ll need to put your JsRender templates into an external file if you plan to use Tumblr Kit on a Tumblr-based site. If you leave them in the page (as in the demo), Tumblr’s tag parser will attempt to process some of the JsRender blocks, as they use a similar syntax to its own custom tags.

JsRender Helpers

JsRender provides a mechanism for registering helper functions to assist with the processing of data within templates. The following helpers are included with Tumblr Kit:

Helper function	Post type	Description
`getHostname()`		Returns the blog hostname as declared in the TUMBLR_HOSTNAME global variable.
`getTintedAudioPlayer(view[, color])`	audio	Returns the embed code for the Flash audio player, optionally tinted with the specified hex `color` value.
`getPhotoURL(view, size)`	photo	Returns the best image URL from available photo sizes based on the specified `size` parameter.
`getPhotoOrientation(view)`	photo	Returns the image’s aspect ratio as `"portrait"`, `"landscape"` or `"square"`.
`getVideoEmbed(view, size)`	video	Returns the best embed code from available video sizes based on the specified `size` parameter.

*Pass #view to the above helpers (where required) to set the current context for the function.

Usage

With your globals and templates declared, importing post data is easy. Tumblr Kit provides a single function to import posts, getTumblrPosts(), which is called on a jQuery selector, like this:

	$("#posts").getTumblrPosts();

By default, this loads the 20 most recent posts from the target blog and renders them inside the #posts element using the JsRender templates defined in your page. When no template ID is specified in the options, the default template naming scheme is expected: #tmpl-audio, #tmpl-chat, etc.

If you include an element inside your container with a class of tumblr-api-loading it will be hidden on completion of the ajax load.

Options

The getTumblrPosts() function takes several settings parameters (all optional).

Option	Type	Default	Value(s)
`hostname`	string	TUMBLR_HOSTNAME	Eg. `"matthewb.tumblr.com"`, `"matthewbuchanan.name"`
`id`	integer	null	The ID of a particular Tumblr post
`type`	string		`"answer"`, `"audio"`, `"chat"`, `"link"`, `"photo"`, `"quote"`, `"text"` or `"video"`
`tag`	string		Eg. `"sports"`, `"tech"` or `"design"`
`limit`	integer	20	The number of posts to load (`1 – 20`)
`offset`	integer	0	The starting index of the first post, useful for implementing pagination
`format`	string		Empty string (for HTML), `"text"` or `"raw"`
`template`	string		The ID of the JsRender template to use for all returned posts, eg. `"#myTemplate"`
`beforeSend`	function	null	Function to run prior to data retrieval
`success`	function	null	Removed, use `done` callback instead
`error`	function	null	Removed (redundant with JSONP)
`complete`	function	null	Removed, use `always` callback instead
`done`	function	null	Function to run upon successful data retrieval
`always`	function	null	Function to run following completion of data retrieval (successful or not)

Use this in your callbacks to refer to the container element(s) defined in the jQuery selector used with .getTumblrPosts(). The done and always callbacks follow jQuery’s deferred objects pattern, and implement the following arguments:

Callback	Parameter	Type	Description
`done`	`data`	object	The data returned by `getTumblrPosts()`
	`textStatus`	string	The status of the successful ajax call (`"success"` or `"notmodified"`)
	`jqXHR`	object	The jqXHR object used in the ajax call
	`uriWithoutOffset`	string	The URL used by the ajax call, minus the offset parameter (if applicable)
`always`	`jqXHR`	object	The jqXHR object used in the ajax call
	`textStatus`	string	The status of the successful ajax call (`"success"`, `"notmodified"`, `"error"`, `"timeout"`, `"abort"` or `"parsererror"`)
	`uriWithoutOffset`	string	The URL used by the ajax call, minus the offset parameter (if applicable)

Version history

0.9.3

Switched callbacks to use the deferred object model (done(), always()).
Removed error() callback as it is redundant with JSONP.
Added URL parameter to callbacks for use with infinite scroll.

0.9.2

Correctly pass the context for this to callback functions.

0.9.1

Added support for before() callback.
Changed approach to hiding the loading message, now requires a class of .tumblr-api-loading.

0.9

Initial public release.

anjihhg/tumblr-kit