XKit

Table of Contents

• Posts
• Adding buttons
• Authorization
• Post Window Listener
• Post Window
• User Information
• Page
• Fetching and Submitting
• Other

Introduction

XKit.interface: returns information about stuff going on on the dashboard.

In the past, each XKit extension individually used jQuery selectors to get information about Tumblr objects such as a post. When Tumblr changes something, all of the extensions would break. By centralizing these calls, changes can be made to XKit.interface and the changes will propagate to all the extensions that make use of the interface.

Posts

# XKit.interface.get_posts(without_tag, mine)

If without_tag is empty, all posts are returned. If it’s not, posts NOT containing that tag will be returned. Use this to add a tag to the posts you’ve already processed.

If mine is true, user’s own posts will be returned.

Returns an array of all posts found.

Example usage:

var posts = XKit.interface.get_posts("quick-tags-not-done", true);
$(posts).each(function() {
     // Do something here.
     $(this).css("background","red");
});

# XKit.interface.post(post)

Takes a post object (ie: this).

Returns information about post on the dashboard.

Returns an object with the following properties:

• id: Post ID (ie: 56977682463)
• root_id: Post Root ID
• reblog_key: Post Reblog key
• owner: Post owner URL (ie: xenix)
• type: Post Type. Can be one of the following:
  • photo
  • photoset
  • quote
  • link
  • conversation
  • audio
  • video
  • note
• tags: Tags on the post, separated by commas.
• liked: true if the user liked this post.
• permalink: Permalink of the post (undefined in some cases)
• is_reblogged: true if this is a reblogged post
• is_mine: true if the post is user’s
• is_following: true if the user is following the owner of this post.
• avatar: URL of the avatar image

Example usage:

var posts = XKit.interface.get_posts("quick-tags-not-done", true);
$(posts).each(function() {
    // Do something here.
    var post_object = XKit.interface.post(this);
    if (post_object.type === "regular") {
        $(this).css("background","red");
    }
});

This will get all the posts that is owned by the user, and turn the text posts red.

# XKit.interface.find_post(post_id)

Wrapper for XKit.interface.post(). Supply the post_id , and if the post is in the dashboard, a Post Object will be returned. If not, a new object with the error set to true will be returned.

Example usage:

var post = XKit.interface.find_post("30219394");
if (post.error == false) {
    alert(post.id + " is the post id.");
} else {
    alert("Oops.");
}

Adding buttons

# XKit.interface.create_control_button(class_name, icon, text, func, ok_icon)

Called once to instantiate a button. Pick a class_name that is unique, supply a base64-encoded image string for icon, a text for the button, and the function to be called when the user clicks the button. You must call this first before adding buttons to posts. ok_icon should be a green version of the icon, to be used with completed_control_button().

Example usage:

XKit.interface.create_control_button("xkit-quick-tags", this.button_icon, "Quick Tags!", function() {
    alert("hello world!");
});

# XKit.interface.add_control_button(post, class_name, additional)

Called for each post to which to add the button. post is the post object, class_name is the button’s unique ID, and additional can be used to add data to the button.

Example usage:

var posts = XKit.interface.get_posts("quick-tags-not-done", true);
$(posts).each(function() {
    XKit.interface.add_control_button(this, "xkit-quick-tags", "");
});

The added button will have the following attributes to make it easier to quickly access the most-used properties of a post:

• data-post-id: Post ID
• data-post-type: Type of the post (see above)
• data-post-permalink: Permalink to the post

Data passed as additional will be added directly to the button. Use it to add any additional data you might need:

var posts = XKit.interface.get_posts("quick-tags-not-done", true);
$(posts).each(function() {
    XKit.interface.add_control_button(this, "xkit-quick-tags", "data-my-data=\"hello\" data-another-data=\"yo!\"");
});

# XKit.interface.disable_control_button(obj, disabled)

Turns the button into a disabled one. The callback won’t be called if disabled is true.

# XKit.interface.switch_control_button(obj, working)

Makes the button show the spinning “working” icon. The callback won’t be called while working is true. Call this when you will be doing stuff like fetching a page and let them know you are working, or when you don’t want the user to click on a button twice.

# XKit.interface.completed_control_button(obj, will_be_green)

Turns the button into a green one. Callback will still fire if the user clicks on it. Checs for class xkit-interface-completed if you don’t want the user to use your button again.

Authorization

# XKit.interface.form_key()

Returns the form key, used to authorize some transactions by Tumblr.

Post Window Listener

Just like Post Listener, executes functions when the user opens a new post / manual reblogging window. Each function is executed once on each window open.

# XKit.interface.post_window_listener.add(id, function)

Add a new function to execute on each window open. You must specify an ID for the function.

Example usage:

XKit.interface.post_window_listener.add("quick_tags", XKit.extensions.quick_tags.post_window);

# XKit.interface.post_window_listener.remove(id)

Removes function from the list.

Example usage:

XKit.interface.post_window_listener.remove("quick_tags");

Post Window

Lets you manipulate or get information from Manual Reblogging / New Post Window.

# XKit.interface.post_window.state()

Returns an object, with the following booleans:

• publish
• draft
• queue
• private

Example usage:

var state = XKit.interface.post_window.state();
if (state.queue) {
    alert("So you are gonna queue this eh?");
}

# XKit.interface.post_window.add_tag(tag)

Tag can be an array or a string. Appends it to the tags list on the window.

Example usage:

XKit.interface.post_window.add_tag("Hello!"); // will add #Hello! to the post.

# XKit.interface.post_window.tag_exists(tag)

Returns true if the tag exists.

# XKit.interface.post_window.remove_tag(tag)

Removes specified tag from the post.

# XKit.interface.post_window.blog()

Returns the URL of the blog the post is going to get posted to.

Example usage:

if (XKit.interface.post_window.blog() === "xenix") {
    alert("Yay, you are posting on my blog.. somehow?");
}

# XKit.interface.post_window.open()

Returns true if the post window is still open.

# XKit.interface.post_window.switch_blog(url)

Changes blog to specified username. Returns true on success.

Example usage:

XKit.interface.post_window.switch_blog("xkit-extension");

# XKit.interface.post_window.type()

Returns an object containing post type information, with the following boolean properties:

• text
• photo
• quote
• link
• chat
• video
• audio

Example usage:

var post_type = XKit.interface.post_window.type();
if (post_type.audio) {
    alert("Yay for audio!");
}

# XKit.interface.post_window.origin()

Returns an object that allows you to check if the user is creating a new post or reblogging one.

var origin = XKit.interface.post_window.origin();
if (origin.is_reblog) {
    alert("Yay for reblogging!");
}
if (origin.is_original) {
    alert("Yay for creating new stuff!");
}

User Information

# XKit.interface.user()

Returns data about the current blog selected:

• posts: Number of posts
• followers: Number of followers
• drafts: Number of drafts
• queue: Number of queued posts

Example usage:

var user = XKit.interface.user();
alert("You have " + user.followers + " followers! Congrats!");

Page

# XKit.interface.where()

Returns information about which page the user is on:

• dashboard: true if user is in dashboard
• inbox: true if user is in inbox/messages
• channel: true if user is in tumblr.com/blog/[blog]

Example usage:

if (XKit.interface.where().dashboard === true) {
    alert("Hooray you are in dashboard now!");
}

Fetching and Submitting

# XKit.interface.fetch(post, callback, reblog_mode)

Makes a request to the Tumblr server to return their post object. post must be the result you get from XKit.interface.post() or XKit.interface.find_post(). When it’s done, the callback will be called with the data or status information. reblog_mode must be set to true for posts not owned by the user.

Example usage:

var post = XKit.interface.find_post("498392831");
if (!post.error) {
    XKit.interface.fetch(post, function(data) {
        if (data.error) {
            // Could not fetch anything!
            alert("Error: " + data.message + "\n" + data.status);
        } else {
            alert("Post tags are: " + data.data.post.tags);
        }
    }, false);
}

Other

# XKit.interface.revision()

Returns an integer with the Interface version.

Example usage:

if (XKit.interface.revision <= 2) {
    alert("I need XKit Interface 3 or above.");
}

This site is open source. Improve this page.