Home

andrewserff edited this page Sep 3, 2011 · 12 revisions
Clone this wiki locally

Table of Contents

Welcome to the tumblr-calendar wiki!

Background

This project was written to fill a specific need. I (Andrew Serff) wanted a way to view all the photos I was posting for my Project 365 (A Photo a Day for a Year) on a calendar. I was using tumblr for my Project 365, so I started looking around for a simple calendar that would let me accomplish this. Well, I didn't find one, so I decided to make my own! I started this project back in January 2011 in my free time. Funny thing about free time, there isn't much of it. I made a little progress and then it sat for a while. I got reenergized by people showing interest in the project by posting on my blog so I was about to start working on it again, then tumblr launched their new (v2) API. I got a bit discouraged by having to rework things for the new API, but I finally had a day of down time and did it. I have the project to a point now to where I wanted to share it with others, so I decided what better way than to open source it and throw it up on github? So here we are, on github, where I hope the project will take on a new life. I likely won't have a ton of time to do much further development, so I encourage all you other developers out there to have at it!

How to use it

Now that we have the background out of the way, on to what you really care about: How you can add the calendar to your own tumblr page!

First, an example

Before you go adding it to your own page, you can take a look at it in action on my tumblr page. As you can see, it will generate a calendar for the entire year month by month and stick a photo from your tumblelog into each day. Each picture is linked to that specific post. If you didn't post a photo that day (which I've been getting worse at...), the day will just have the date in it.

tumblr changes

To add the calendar to you own page, you need a few things:

  • A tumblr account obviously
  • You own tumblr API key for your page to make requests to the tumblr API. You can get your own key by going here: http://www.tumblr.com/oauth/apps Register your application with some name like "Johnnys photo calendar." You need your own API key so that you can track usage and tumblr can yell at you if you get too many people looking at your awesome photo calendar instead of me. ;)
  • You will need to create a javascript file and have it hosted somewhere accessible on the internet. I called my baseUrl.js and hosted it on my own webserver. (This is due to what seems to be a limitation of tumblr itself. If you try to put plain javascript in a page, it wraps it in multiple CDATA sections and it becomes invalid. If anyone knows how to get around this, please let me know). Within this javascript file, you are going to define a single javascript variable called baseUrl. This is the baseUrl to the API call for you specific blog including the API key. For example, this is what is in my baseUrl.js file:
var baseUrl = "http://api.tumblr.com/v2/blog/tumblr.serff.net/posts?type=photo&api_key=myapikey";
You will need to change "tumblr.serff.net" with the url to your blog. (i.e. johnny.tumblr.com or something along those lines) You will also need to replace myapikey with you actual API key you registered in step 2.
  • Log on to tumblr and go to customize your page. (While logged into tumblr, I go to http://tumblr.serff.net and hit the customize link in the top right of the page.)
  • Add a new Page from the Pages menu
  • A new window should pop up. Leave the defaults. Then in the "Body" section, click the "HTML" button that will pop up a new window and let you enter custom HTML for the page.
  • Paste the following into that page:
 <script type="text/javascript" src="https://raw.github.com/sunkencitysoftware/tumblr-calendar/v1.0.0/js/prototype.js"></script>
 <script type="text/javascript" src="https://raw.github.com/sunkencitysoftware/tumblr-calendar/v1.0.0/js/tumblr-calendar.js"></script>
 <script type="text/javascript" src="LOCATION TO YOUR baseUrl.js FILE"></script>
 <script type="text/javascript" src="https://raw.github.com/sunkencitysoftware/tumblr-calendar/v1.0.0/js/tumblr-calendar-gen.js"></script>
  • Hit the Update button
  • Give you name a page (and a title if you want). I would recommend not checking the "Show a link to this page" until you make sure it works.
  • Hit Save
  • Go test it out! When you load the page, you should see it sit there for a little bit while it gets all the photos and then draw you calendars.

More details

  • The script is written in Javascript
  • The script relies on the [Prototype](www.prototypejs.org).
  • This script works cross domain. It will use the baseUrl you provided and it generates script tags and shoves them into the page until it gets all the photos for the current year. Therefore, it doesn't use AJAX to make these calls and can therefore be used on any domain (not just a tumblr page either...)

Known Limitations/Issues

  • Like I said, this was made for a specific purpose: a photo calendar. Therefore, in your baseUrl, we specify we only want photo posts(type=photo). Also, the javascript library expects to get photos from the tumblr response. If it doesn't, I don't know what will happen. I assume it will break horribly. You have been warned. :)
  • It will only get photos for the current year.
  • I've had weird results with tumblr and added the page. Sometime, you add the HTML, hit update, and save the page and go to the page and it is like you never did anything. This is a tumblr issue...not much I can do there.