Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/matthewbuchanan/tumblr-kit
A jQuery plugin for importing post data from Tumblr’s API.
https://github.com/matthewbuchanan/tumblr-kit
Last synced: 18 days ago
JSON representation
A jQuery plugin for importing post data from Tumblr’s API.
- Host: GitHub
- URL: https://github.com/matthewbuchanan/tumblr-kit
- Owner: matthewbuchanan
- Created: 2012-06-13T22:00:53.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2016-01-07T22:42:59.000Z (almost 9 years ago)
- Last Synced: 2024-08-01T00:45:38.532Z (3 months ago)
- Language: HTML
- Size: 29.3 KB
- Stars: 87
- Watchers: 4
- Forks: 12
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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](https://dl.dropboxusercontent.com/u/25640/tumblr-kit/demo/index.html).
## Dependencies
Tumblr Kit requires [jQuery 1.5+](http://jquery.com) and [JsRender 1.0pre+](http://github.com/borismoore/jsrender/).
## Setup
Include the dependent frameworks listed above:
```html
```
Declare global variables for your Tumblr OAuth Consumer Key ([register one here](http://www.tumblr.com/oauth/apps)) and your blog’s hostname:
```html
var TUMBLR_API_KEY = "U41Qn………0e6aR";
var TUMBLR_HOSTNAME = "matthewb.tumblr.com";
```
Replace the values above with your own credentials.
### Use in public themes
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](http://www.tumblr.com/docs/en/custom_themes#appearance-options) tag for the Consumer Key and output the blog’s hostname using the undocumented `{Host}` tag:
```html
var TUMBLR_API_KEY = "{text:Tumblr OAuth Consumer Key}";
var TUMBLR_HOSTNAME = "{Host}";
```
## Post templates
Tumblr Kit uses [JsRender](http://github.com/borismoore/jsrender) templates to define the markup for each imported post. JsRender supercedes the now-deprecated [jQuery Templates](http://api.jquery.com/jQuery.template/) plugin. Boris Moore provides basic [demos and documentation](http://borismoore.github.com/jsrender/demos/) for JsRender, and I’ve put together a [sample template](http://github.com/matthewbuchanan/tumblr-kit/blob/master/sample-jsrender-templates.md) 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:
```html
<article id="post-{{:id}}" class="post-{{:type}}">
<h1>{{:title}}</h1>
{{:body}}
</article>
```
Tumblr’s [API documentation](http://www.tumblr.com/docs/en/api/v2#text-posts) 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:
```javascript
$("#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](http://api.jquery.com/category/deferred-object/) 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.5**
- Switch to protocol-agnostic API fetching.
**0.9.4**
- Patched Cycle Lite plugin due to removal of $.browser from jQuery.
**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.
## License
The Tumblr Kit source is copyright © 2012 by [Matthew Buchanan](http://matthewbuchanan.name) and released under the [WTFPL license](http://sam.zoy.org/wtfpl/).