Tumblr Tag Cloud Widget

Version 1.9.1   --   Updated Jan 17, 2013

Outline

  1. Introduction
  2. Generate your Script
  3. Frequently Asked Questions
  4. Styling your Tag Cloud

Introduction

I have previously used a Tag Cloud script by Heather Rivers. Her script is great, except:

  • It takes forever to load when your tumblr has more than a few hundred posts.

    • Heather's script loads every single one of your posts from the Tumblr API every single time your page is accessed by anyone. It's slow and wasteful.

Advantages of my Script:

  1. Your Tag Cloud loads much faster because my server has already downloaded your Tags from Tumblr and cached them for performance.

  2. The script is very simple and averages about 6 kB in size with all Tag data included.

  3. I have many additional options to control how your Tags are displayed.

Disadvantages of my Script:

  1. Because your tags are cached for performance, tags for new posts, or changes to tags on existing posts, will not appear immediately on your Tag Cloud. Updates are frequent, but you can expect a normal delay of about 30 minutes.
  2. This Script is primarily intended for blogs with many hundred or thousands of posts. If your blog has less than about 300 posts, you may prefer the non-cached behaviour of Heather's Script. Her script will load in about 1 second per 100 posts on your Tumblr.

Generate your Script

Tumblr Name:   eg, my-tumblr-name.tumblr.com
Sort Tags
Max # Tags ( show at most this many tags;  the default is 1000 )
Min Tag Freq. ( only show a tag used at least this many times )
Scale Tags?
Scaling Math
Max Font Size % ( default: 240   recommended: 200 - 400 )
Base Font Size ( default: leave it alone )
Text Case
Show Tag Count? format:  
Scale tag count?
Display Tags as
Comma b/w Tags?  
Extra space b/w tags? pixels
Prevent Tag Wrap?
Language Code Enter a 2 or 3 letter ISO-639 code;   recommended when using Alphabetical sorting if your tags are not in English!
Exclude these tags:   (Separate tags with commas. Capitalization does not matter.)

This is your Code:

copy & paste to your Tumblr Theme or Page

This is an example of your Tag Cloud

Installing the Tag Cloud Script

  1. Where do you paste the code?

    • On a "Page" on your Tumblr

          Click here for a Tutorial

    • In your Tumblr “Description”

      You can paste the code directly into the "Description" field on your Tumblr Customize page.

      On some Tumblr Themes, this will look nice, putting the Tag Cloud in a sidebar or header or something similar.   On other Themes, it may look horrible!

      Click here for a Tutorial

    • In your Tumblr Theme Code

      You'll need to know the basics of HTML to do this correctly.

      For most people, figuring out where to paste the script in your Theme HTML is the tricky part. You cannot just paste the script anywhere in your Theme.

      I suggest you use the "Search" (Ctrl+F) in your browser on the "Edit HTML" screen on your Customization page to locate some text in your Theme Code near where you want your Tag Cloud to display. You might have to play with it a bit to get it just right.

      If you need help, you can ask me on Tumblr, and I will try to assist you if I can.

    • In a "Text" Post

      You can paste the code in a Text post, however it will not show up on the Tumblr Dashboard. People will have to open the post on your Tumblr Page to see the Tag Cloud.

      Click here for a Tutorial

  2. If you have Thousands of Posts –

    • This Tag Cloud will only list the Tags from the most recent 5,000 posts on your Tumblr.

      Sorry, but it's just too much load on my server to download more than that.

  3. If you need help, or things are not working

    If you need help, or think something is broken, you can send me a note on Tumblr or shoot me an e-mail. I will try to help you out, because I'm just a nice guy like that.   :)

  4. Please read the FAQ!

 

Frequently Asked Questions

  1. I changed my Tumblr name, and now my Tags are not showing up!

    Your Tag Cloud is connected to your Tumblr name.  Unfortunately, there is no way for me to know when your Tumblr changes names. It just looks like your Tumblr disappeared.

    You need to Re-generate your Script for your New Tumblr Name, and replace the old script code on your Tumblr page.

  2. I just posted something, and the Tag Cloud didn't update!

    The tag cloud is cached.  It is updated frequently, but not immediately.

    Caching is good because it means your tags load fast. The downside is that it takes a short while for new changes to appear. Sorry folks, that's just how it works.

    You may request a refresh to update your tags if you really can't wait for the cache to automatically update.

  3. I changed/removed some Tags on my posts, but the changes aren't showing up!

    Again, the tag cloud is cached.  It is updated frequently, but not immediately.

    In particular, your tags are only updated when I detect that your Tumblr has a new post.

    So if you edit tags on old posts or delete posts, these changes will not show up on your cloud until:
         1. You post something new on your Tumblr
         2. The cache automatically updates itself

    Otherwise, you may request a refresh to update your tags if you really can't wait for the cache to update itself.

  4. How often are the tags updated?

    This gets a little complicated.  For most people, I think the answer is "often enough".

    At the bare minimum, your tags are updated every 6 hours.

    Then, every time someone visits your Tumblr page, if it has been at least 20 minutes since the last time your tags were updated, I check if your tumblr has any new posts. If your tumblr has any new posts, the tags from the last 50 posts on your tumblr are updated.

    A complete refresh is done every 24 hours, just in case you deleted any posts, or changed any tags on old posts.

  5. I have a tag like "my-hyphenated-tag" and it doesn't work when I click on it!

    This is a well-known Tumblr bug for tags containing a hyphen / dash ( - )

    In fact, all of the following characters have issues:

    •   “ - ”     is converted to a space

    •   “ + ”     is converted to a space

    •   “ _ ”     is converted to a space

    •   “ / ”     does not work at all

    When I say "is converted to a space" I mean that the tags "some-tag", "some+tag" and "some_tag" will all actually link to the tag "some tag", so they not find any posts whose tags have the hyphen, plus or underscore in them.

    If I were you, I would avoid using any of these characters in your Tags.

  6. I have a Private Tumblr, will the Tag Cloud work?

    No.  Unfotunately, private does mean private.

    Temporarily removing the password from your Tumblr will not work either. Once your Tumblr is marked "private" again, my server will delete your Tag Cloud within 24-48 hours. So don't even bother trying that.

  7. Is this free?

    Yes, this Tag Cloud script is "Free as in Free Waffles"

    Free Waffles come with butter and maple syrup,  Yum!

    But that's it:  there's no warranty, guarantee, or money back (hey, they're free), and if you eat them, you assume any risk (ie, don't blame me if you get sick) etc.

    More specifically,

    By using this Tag Cloud, you agree to the Tag Cloud License and Terms of Service.

    The Tag Cloud comes "as-is", with no warranty of any kind, and I disclaim any liability arising from its use

    I will not make any claim to constant availability of this service, now or in the future.

    There may be brief periods when the Tag Cloud will not load correctly ("downtime"). It happens, it's annoying, it's not always my fault. But I can't make any guarantee for 100% uptime.

    I reserve the right to disable this service at any time, or to block any particular Tumblr, IP, user etc. at my sole disgression.

  8. And you're not going to insert advertisements or something are you?

    No. I will never do that, don't worry.

  9. Do you have a Privacy Policy?

    Yes I do, you can Read my Privacy Policy here.

  10. Do you offer support?

    Not in any official way (unless you want to pay me!)

    But I do want my tool to be useful! So please do:

    • Send me bug reports!

    • Let me know if something is broken or not working correctly!

    • Request new features!

    • Ask me questions if anything is confusing!

    If you need help with "How do I put the Tag Cloud in my Tumblr Theme?"

    • Help with this is offered "out of the goodness of my heart", when and if I have time.

    Please direct any questions or whatever to my Tumblr Ask Box or send me an e-mail.

  11. What Browsers are supported?

    Browsers I have tested –

    • Internet Explorer 8 on Windows XP

    • Internet Explorer 9 on Windows 7

    • Internet Explorer 10 on Windows 7

    • Firefox 10 - 18 on Windows 7

    • Google Chrome 15 - 23 on Windows 7

    I have no plans to support IE < 8

    I don't have a Mac, iPhone, or iPad so I can't test Safari, but it should work the same as Chrome.

    I don't have an Android phone or tablet, but I have been told the cloud works OK on Android based phones/tablets.

    Occaisonally, something else in your Tumblr Theme may interfere with the tag cloud script. The usual suspects are other JavaScripts that cause unexpected changes to the document before the Tag Cloud gets a chance to run, some invalid HTML in your Theme, or an element in your Theme that uses the element id "tagCloud".

    I've fixed some of these issues, especially regarding various "infinite scroll" scripts on people's Tumblr Themes.

    Of course if you find a bug, please drop me a note on Tumblr, or send me an e-mail

 

Styling your Tag Cloud

If you want to change how the Tag Cloud looks on your Tumblr, you need to do it yourself.

These are only Some Examples

On your Theme Customization page, go to the bottom of the left side, click where it says "Advanced". On most Themes, you can paste these examples where it says "Add custom CSS".

  • Changing the color of the tags:

    #tagCloud a, #tagCloud a:visited { color: ForestGreen; } #tagCloud a:hover, #tagCloud a:active { color: LimeGreen; }

    You can read more about CSS Colors

  • Getting rid of the "underline" on tags:

    #tagCloud a { text-decoration: none; }

  • Adjusting the width of the cloud:

    #tagCloud { width: 300px; }

    Sets the cloud to be no more than 300 pixels wide

  • Containing your Cloud in a Fixed Box:

    #tagCloud { width: 300px; height: 600px; overflow: hidden; }

    The cloud will b no more than 300 pixels wide, 600 pixels tall. Anything that does not fit in that rectangle will be hidden on your page.

  • And of course you can combine multiple options, like this:

    #tagCloud { text-align: center; } #tagCloud a, #tagCloud a:visited { color: Black; text-decoration: none; } #tagCloud a:hover, #tagCloud a:active { color: Red; text-decoration: none; }

    Sets Tags to be "centered", sets Tags to be Black in color (but Red when you have your mouse over the tag), and eliminates the "underline" on the links.

    Some things that may help you:

  • If you're going to be writing your own CSS, you might want to know how the Tag HTML is rendered on your page:

    <div id="tagCloud" class="tc-loaded"> ... <span class="tc-tag" style="font-size: XXX%;"> <a class="tc-link" title="N Posts" href="/tagged/TagName">TagName</a> </span> ... </div>