Meet the Tumblr API + Markup!

This quick sandbox post is primarily for people who:

 

– are familiar with using Tumblr as a casual blogging platform,

– have some basic sense of HTML, and 

– want to combine these skill sets to make a custom process blog for DH project(s).

What is the Tumblr API?

 

An Application Programming Interface (API) is a just an overly technical term for how a set of software works—i.e. what information it has access to (variables) and the ways it knows how to interact with that information (functions). So the Tumblr API (which lives here, by the way) refers to things and tools that you as an up-and-coming Tumblr developer have access to, including the content of that last text post you made, what time you made it, how many notes it has, how to retrieve the URL of the blog you just reblogged that picture from, and whether or not your are following that blog. All of this information gets stored in Tumblr servers and databases every time anyone is interacting with their platform, and the API is how you can request it, use it, and make it look cool. 

For reference, below is what some of this information looks like in its raw metadata form. 

 

"blog_name":"museumsandstuff",,,
"id":: 4742980381,,
"post_url":: "http://museumsandstuff.tumblr.com/post/4742980381",,
"type":: "quote",,
"date":: "2011-04-19 08:52:34 GMT",,
"timestamp":: 1303203154,,
"format":: "html",,
"reblog_key":: "KLA85e6c",,[],
"note_count":: 23,,
"source_url":: "http://museumtwo.blogspot.com/2011/04/guest-post-convivial-museum-photo-essay.html",,
"source_title":: "museumtwo.blogspot.com"

 

And below is what using the Tumblr API ‘markup’ to interact with that metadata looks like. This is the stuff you need to make a custom theme. While it is certainly useful to understand the API and metadata structures (above), you only need to know a little bit of it to start making themes.

<html>
    <body>
        {block:Posts}
            <div class="post">
                {block:Text}...{/block:Text}{block:Photo}...{/block:Photo}
                ...

                {block:HasTags}
                    <ul class="tags">
                        {block:Tags}
                            <li>
                                <a href="{TagURL}">{Tag}</a>
                            </li>
                        {/block:Tags}
                    </ul>
                {/block:HasTags}
            </div>
        {/block:Posts}
    </body>
</html>

 

Step 1: Look under the hood.

 

To start tinkering with your Tumblr theme, go to your Tumblr blog and find the ‘Edit Theme’ button in the top right corner. This will take you to  http://tumblr.com/customize/YOUR-URL.

A sidebar will pop up on the left of your blog. At the very top will be a ‘Custom Theme’  pane with an ‘Edit HTML’ link.

Click it, and you’ll find yourself in a sidebar window where you can edit the Tumblr markup and HTML. Click ‘Update Preview,’ and you’ll immediately see changes to your Tumblr theme. If you’re familiar with HTML you’ll see some friendly faces like the <head> and <body> tags, as well as <h1> or maybe <li>. Among these tags you’ll find a lot of variables and blocks (the things in {curly brackets}). 

The variables and blocks in curly brackets are what allows themes to be abstract, meaning that the HTML and CSS of the theme you make can be applied to the content of any blog. The variables and blocks stand in for abstract information, for example: {Title} is a theme placeholder that tells the browser “go fetch this blog’s actual title” when its needed. Similarly, “{block:Photo} <img src={PhotoURL-500}/> {/block:Photo},” tells the browser “if this blog has photo posts, render them according to the HTML I wrote between the {block:Photo} and {/block:Photo}.” This way, you don’t need to tell the theme what the specific title actually is or what the photo URLs actually are; instead you can use Tumblr markup variables and blocks to tell it where to find that info if/when it needs to.

Step 2: Start from scratch! 

 

Now that we’re under the hood and looking at all the HTML tags and Tumblr blocks/variables, odds are that the theme you have in there right now is incredibly complicated and unintuitive to read. So go ahead and select everything in the HTML editor and delete it. Notice how, if you hit ‘save’ or ‘update preview’ at this point, your blog will be a completely blank window, without even a hint of your blog’s content. This doesn’t mean that content is gone in terms of your actual blog, it just means your page doesn’t know how to find or engage it anymore. 

Now you need to re-add Tumblr to your Tumblr, so copy and paste the following bare-bones markup theme into your editor:

<html> 
    <head> 
         <title>{Title}</title> 
         <link rel="shortcut icon" href="{Favicon}"> 
         <link rel="alternate" type="application/rss+xml" href="{RSS}"> 
         {block:Description} 
             <meta name="description" content="{MetaDescription}" /> 
         {/block:Description} 
     </head> 
     <body> 
         <h1>{Title}</h1> 
         {block:Description} 
             <p id="description">{Description}</p> 
         {/block:Description} 
         <ol id="posts"> 
         {block:Posts} 
             {block:Text} 
             <li class="post text"> 
                 {block:Title} 
                     <h3><a href="{Permalink}">{Title}</a></h3> 
                 {/block:Title} 
                 {Body} 
             </li> 
             {/block:Text} 
             {block:Photo} 
             <li class="post photo"> 
               <img src="{PhotoURL-500}" alt="{PhotoAlt}"/> 
                 {block:Caption} 
                     <div class="caption">{Caption}</div> 
                 {/block:Caption} 
             </li> 
             {/block:Photo} 
             {block:Photoset} 
             <li class="post photoset"> 
                 {Photoset-500} 
                 {block:Caption} 
                     <div class="caption">{Caption}</div> 
                 {/block:Caption} 
             </li> 
             {/block:Photoset} 
             {block:Quote} 
             <li class="post quote"> 
                 "{Quote}" 
                 {block:Source} 
                     <div class="source">{Source}</div> 
                 {/block:Source} 
             </li> 
             {/block:Quote} 
             {block:Link} 
             <li class="post link"> 
                 <a href="{URL}" class="link" {Target}>{Name}</a> 
                 {block:Description} 
                     <div class="description">{Description}</div> 
                 {/block:Description} 
             </li> 
             {/block:Link} 
             {block:Chat} 
             <li class="post chat"> 
                 {block:Title} 
                     <h3><a href="{Permalink}">{Title}</a></h3> 
                 {/block:Title} 
                 <ul class="chat"> 
                 {block:Lines} 
                     <li class="{Alt} user_{UserNumber}"> 
                         {block:Label} 
                             <span class="label">{Label}</span> 
                         {/block:Label}
                         {Line} 
                     </li> 
                 {/block:Lines} 
                 </ul> 
             </li> 
             {/block:Chat} 
             {block:Video} 
             <li class="post video"> 
                 {Video-500}
                 {block:Caption} 
                     <div class="caption">{Caption}</div> 
                 {/block:Caption} 
             </li> 
             {/block:Video} 
             {block:Audio} 
             <li class="post audio"> 
                 {AudioEmbed}
                 {block:Caption} 
                     <div class="caption">{Caption}</div> 
                 {/block:Caption} 
             </li> 
             {/block:Audio} 
         {/block:Posts} 
         </ol> 
         <p id="footer"> 
             {block:PreviousPage} 
                 <a href="{PreviousPage}">« Previous</a> 
             {/block:PreviousPage}
             {block:NextPage} 
                 <a href="{NextPage}">Next »</a> 
             {/block:NextPage} 
         </p> 
     </body> 
</html>

You’ll notice that, when you save and refresh the page, any your blog title, description, and any posts you have will appear in an ordered list <ol> format, with an automatic pagination setting that lets you click through to the next page of posts. This is the Tumblr markup at work. Next we’ll look at how to style it with targeted HTML and CSS.

Step 3: Target Post Elements with Classes and IDs

Tumblr Post Types

There are seven post types (actually, eight) offered by Tumblr with their own attributes in the post interface:

 

(1) Text posts (with text {Title} and text {Body} attributes),

(2) Quote posts (with {Quote} and {Source} attributes),

(3) Link posts (with {URL}, {Title}, and {Description} attributes),

(4) Chat posts (with chat {Title} and a series of {Lines} for the dialogue),

(5) Audio posts (with {AudioEmbed} and {Caption} attributes),

(6) Video posts (with Video / {Video-500} and {Caption} attributes),

(7) Photo posts (with Photo / {Photo-500} and {Caption} attributes), that automatically become

(8) Photoset posts when more photos are added.

 

These are dynamic Tumblr variables that automatically target the information you put into the Tumblr dashboard interface on an ongoing basis. In addition to more static variables like your blog’s {Title} or {Description}, they are the things you want to wrap with specific html elements, IDs, and classes and in order to target them with CSS styling and, if needed, Javascript functions.

For example, if you want your Tumblr blog to render the title you put into your interface in a fancy cursive font that is distinctive from the rest of the text on your page you might write the following html and Tumblr markup right after your <body> tag:

 

<h1 id="blog-title"> {Title} </h1>

 

And then in CSS (either in a separate style.css file or in between your <style> </style> tags), target that specific Tumblr variable with the ID you assigned to it:

 

#blog-title{font-family: cursive;}

 

Or, if you want each post that has a title to show that {Title} attribute in cursive, you might add a class to the <h3> tag surrounding each post title:

 

{block:Text}
    <li class="post text">
        {block:Title}
            <h3 class="cursive-title"><a href="{Permalink}">{Title}</a></h3>
        {/block:Title}
       {Body}
    </li>
{/block:Text}

And then in CSS, target all the post titles with the class you made (same as before):

 

.cursive-title{font-family: cursive;}

Step 4: Do More Research and Dive In

 

That is the basic framework for integrating the Tumblr markup and platform into your HTML and CSS to make a dynamic theme. After playing around with targeting elements that wrap around Tumblr variables like in the example above, it’ll be worth looking into a more comprehensive source for Tumblr development, like http://buildthemes.tumblr.com/, where you’ll learn how to implement more complex functionalities like infinite scroll and <meta> tags.

 

Mariel Nyröp
Follow Mariel Nyröp:

5CollDH Technologist in Residence

Mariel / Marii Nyröp is the Post-Baccalaureate Technologist-in-Residence at 5CollDH. You can contact Marii here.