Freitag, 3. September 2010

flattr plugin for blogger.com/blogspot.com

I've completely reworked my old flattr plugin. The new version supports the new API v0.6. As the old API is deprecated now, it makes sense for all bloggers to switch to the new version.
There are three pieces of code to paste in now, but it's still not really complex.

clubber plex did a Spanish adaptation of the step by step part of this post, so if you prefer Spanish over English, go here. It doesn't include the explanations part, though, so if you experience problems, come back here and read the rest.

Here's the instructions:
s.src = 'https://api.flattr.com/js/0.6/load.js?mode=manual&uid=12345&category=text&language=de_DE';
  • Change the uid entry to your flattr user id or user name. I don't mind if you keep 12345 for tests; this is not some random test uid but actually my real flattr uid. :-) But don't forget to change the uid once you install it in your real blog!
  • If you don't blog in German, change the language entry to an appropriate setting (use only values from this list).
  • If you want large buttons, look down to the line that begins with document.write( and change button:compact to button:default there.
  • Go to the Design tab in blogger.com and choose the 'Edit HTML' sub-tab. (If these are named slightly differently in English, please forgive me, this is translated back to English from German. If I'm wrong, please tell me so in the comments and I'll correct it.)
  • Download the complete template and save a backup copy of it so you can go back to a working version if something goes wrong.
  • Open the template in a text editor.
  • Find the <head> tag at the beginning of the file. Directly after that tag, insert the complete contents of your edited blogger-flattr-plugin-head.txt.
  • Find the </body> tag at the end of the file. Directly before that tag, insert the complete contents of blogger-flattr-plugin-footer.txt.
If you know what you are doing, you can now take the complete contents of blogger-flattr-plugin-body.txt, maybe tweak them to your likes and paste them wherever you want your flattr buttons to show up.
To get my layout, do the following:
  • Find the following lines in your blogger template:
<div class='post-body entry-content'>
  <data:post.body/>
    <div style='clear: both;'/> <!-- clear for photos floats -->

  • Paste in the complete contents of blogger-flattr-plugin-body.txt after those lines.
  • If your template doesn't contain these lines, find <data:post.body/> and paste the stuff somewhere between that and where the enclosing div tag is closed. Some tweaking might be required to achieve sensible positioning.
Update: If you want to place the button in the footer beside the share buttons, look at BrunoB's solution here. (I didn't test that myself, but his blog looks good.)
    Now you're nearly done! You only have to upload your edited template to blogger.com, and if you didn't do anything wrong, all will be good. ;-)

    This plugin is still based on the works of Mattias Bomelin and Nicholas Gramlich, though I did a major rework to adapt it to the new API.

    If you have a flattr button for the whole blog like I have at the right, be sure update it to the new API, too, if you haven't done so already.
    Also, Mattias from flattr recommended not to use the button parameter in conjunction with load.js, so I moved that down to the button definition itself. Now, hopefully, everything should work.

    Caveat: If you get an error for a single post but not for others, this could be because the post's title or the post itself is shorter than 5 characters. flattr doesn't support a title or a description (which is where your post ends up) that is shorter than 5 characters. If you have a suggestion how I could fill the space up without garbling the flattr thing for posts with titles like "uh", please send me an email. For the time being, just use titles and posts longer than 5 characters.

    Known problem: Internet Explorer 7 only shows errors in buttons for posts that have not been flattred yet. The other buttons work. I don't know if that's caused by flattr's API or by my JavaScript coding, and I won't look into it any further as it does work with all current browsers, including IE 8. But if you have a hint how this could be solved, I'll happily integrate it, of course.

    If you're experiencing other problems, mail your edited template to the contact email address. I'll look into it when I have time to. This means don't expect a response within 24 hours, it might take weeks.
    And I do expect that you tried everything you could think of yourself before you emailed me. I will not even answer requests to do all the work for you—it's really not that complicated, and there's step-by-step guidance above!
    I hope this works as well for everyone else as it does for me. If not, please comment or send an email!
    Happy flattring to all of you!

    Small Update: The truncation of the actual text did not work as expected: Should have truncated at a space and added "…", instead it simply truncated at char 980, possibly chopping words in the middle. Turns out JavaScript regular expressions don't work on multiline strings. :-)
    The new version first replaces all newlines by spaces, and voila, truncation works as it should. (I only changed blogger-flattr-plugin-head.txt, the others stayed as they were.)

    How the flattr API works
    As several users thought they were experiencing problems while everything was perfectly ok, here are some explanations about how flattr's API works and how everything looks like if it's ok:
    First, don't expect a flattr thing to magically appear for all your ten-thousands of old posts in your blog. A post will be submitted to flattr.com and created as a flattr thing there at the moment when the first user clicks the flattr button.
    Before that (i.e. while the button still shows the number zero), there is no flattr thing.
    This also means that while buttons with one or more flattrs have a link to the flattr thing at flattr.com in the white area around the number, buttons with zero flattrs don't. If you manually create a flattr thing for a post at flattr.com, also not-yet-flattred buttons will have a link to the thing.
    Second, you can't flattr yourself. That's why all the buttons on your blog show "My thing" (or only "My" on some browsers) and are not clickable while you are logged in at flattr.com.
    You can see what others see if you log out at flattr.com, but trying to flattr a post will then only take you the flattr login page, of course. If you want to test if flattring is possible at all, you'll have to ask a friend who also uses flattr to test-flattr one of your posts.

    Legal stuff: The plugin is published hoping that it will help and comes with no warranty whatsoever, of course. Use it at your own risk. If proper or improper use leads to any kind of damage, I can not be held liable. You are free to use the plugin free of any charges or claims and change the code as you like. If you redistribute it in altered or unaltered form, please link back to this post.

    Kommentare:

    1. Thanks for this excellent and easy to use guide. It worked perfecr for my blog located at http://kimme.blogspot.com/

      I flattr'ed your guide.... :)

      AntwortenLöschen
    2. Thanks a lot for that nice plugin!

      AntwortenLöschen
    3. Is there actually a way to show these ugly buttons only at the bottom of the „full“ article and NOT at the bottom of the abstract on the main page?

      AntwortenLöschen
    4. Hm, Might or might not be possible. If you look at the elements like the comment form that are only available in article view you might find a solution. If you don't send me an email and I will have a look. Might take some time, though.

      AntwortenLöschen
    5. Just installed your plugin on my blog. However, it seems most of the flattr buttons can't be clicked (no cursor change when you mouseover them or tooltip popup). Only the most recent one seems to actually work. I'll hunt for answers but wanted to make you aware in case you know a fix.

      Blog is here: http://family.bob-space.com

      Thanks for publishing this plug-in! You got a flattr from me.

      AntwortenLöschen
    6. Hi Bobus,

      your blog looks good to me (using Firefox 3.6), all buttons are ok. Did you change something meanwhile or did it just mysteriously fix itself? :-)

      AntwortenLöschen
    7. I don't have Firefox installed, but in both Chrome and IE the top-portion of the flattr button (where the number of flattrs is displayed) is not clickable, the "view this on flattr.com" tooltip does not pop up, and the mouse cursor does not change. You are correct that the bottom "flattr this" portion of the button does seem to work as intended.

      Oddly, the top-half of one flattr button does work correctly for one of my older posts. I'm guessing this is because I manually submitted that post to flattr (and so it has a corresponding flattr URL in the flattr.com database)? Does your plug-in submit posts to the flattr.com directory? Or does this still need to be done manually to have them appear there?

      Thanks so much for the help!

      AntwortenLöschen
    8. I figured it out. It was as I suspected. You have to manually submit your post to the flattr.com directory. Once it is in the directory the flattr button for that post will correctly link to the directory entry.

      Sorry for the confusion!

      AntwortenLöschen
    9. Hi Bobus,

      actually, the plugin will submit a post to flattr at the moment when the first person flattrs it. From then on, the number in the button will be a link to the flattr thing. I guess I should make that clearer in the post above. I'll add some sentences about this these days.

      AntwortenLöschen
    10. Right, the template I'm using has none of the 'body' html that you mention in your post above so I can't figure out where to put the body code.

      I now remember why I stopped using blogger. their templating system is awful and makes absolutely no sense.

      AntwortenLöschen
    11. @Mandrill: You did download the template, didn't you?

      Because if you just look at it in your blog's settings and did not tick the box that says you want to see all widgets, you won't see the complete template, and you won't see the stuff I wrote about, too.

      AntwortenLöschen
    12. hey, thanx!

      everything is cool except from .. when my site [http://arxediamedia.blogspot.com]is being loaded , it freezes for a few seconds trying to load the api.flattr.com
      i find this a serious lag
      could we expect some improvement on that either on your how-to or flattr.com ?

      thanx again

      AntwortenLöschen
    13. Well, there's not much I can do myself, only flattr could speed up their servers. Of course, you could also reduce the number of flattr buttons on your blog by setting the number of posts per page to a lower value.

      Apart from that, on very slow machines the Javascript might require some time to be processed, especially if you have very long posts, but so do I, and the slowing down I see is not really recognisable, except when the flattr servers are slow, which seems to be different from time to time.

      You could also post at the flattr forums or write an email to their support and ask for better server speed

      AntwortenLöschen
    14. Thank you for your help , in return I give you my first flattr :) !

      AntwortenLöschen
    15. My button says "My thing" instead of flattr. Any ideas?!

      Thanks
      http://5tth.blogspot.com

      AntwortenLöschen
    16. Please read the part "How the flattr API works" above again.

      AntwortenLöschen
    17. I'm having trouble getting this to work. Could you help me out? http://www.biculturalmom.blogspot.com

      AntwortenLöschen
    18. @Chantilly: Uh, you're blog looks heavily customzied, I can imagine that this might be problematic. Please send an email using the "Kontakt" link in the right column and attach your Blogger template XML to the email (including your edits to add flattr; please don't send the template without changes).
      I'll look into when I have time to, but it might take a few days.

      AntwortenLöschen
    19. Lol. I am customizing quite a lot and new to html, so I know there have got to be some errors in there. Thanks for offering to help. I'll send the XML template to your inbox. =)

      AntwortenLöschen
    20. Not if you want a button below every post. But it's really not difficult, you don't have to understand what you are doing, after all. ;-)
      If you're unsure, just create a second blog in Blogger that you can use exclusively for testing.

      AntwortenLöschen
    21. Danke - genial! Hat funktioniert! Und ich hab dich gleich geflattrd : )

      AntwortenLöschen
    22. Hi there!

      First of all, Danke for your help! I'm completely ignorant about editing and all that stuff, but I followed your instructions and finally managed to add my flattr button in my blog.

      The point is it doesn't work :-(

      Will you please help me with it? I'm eager to learn it all and make a Spanish version from your instructions.

      Danke again!

      AntwortenLöschen
    23. @clubber plex: Please send a detailed (!) description of what exactly is happening to the email address linked as "Kontakt" at the right column. And be specific, "it doesn't work" is not enough to be able to help. ;-)
      When your Spanish version is ready, please tell me and I'll link to it.

      AntwortenLöschen
    24. Vielen Dank für die Anleitung. Hat alles wunderbar geklappt. ;-)

      AntwortenLöschen
    25. Thanks a lot, works perfect for me ;)

      AntwortenLöschen
    26. Vielen, vielen Dank für die Anleitung. Nun müssen wir nur abwarten, ob unsere Sachen auch geflattrt werden. Gruß aus Berlin, Stephan & Georg
      frequenz9.de

      AntwortenLöschen
    27. Danke für die Anleitung!

      AntwortenLöschen
    28. Nun ich bin euch für die Anleitung sehr dankbar.

      AntwortenLöschen
    29. the template I'm using has none of the 'body' html that you mention in your post above so I can't figure out where to put the body code.

      AntwortenLöschen
    30. Did you download the template or did you just look at it in the Edit HTML tab? If the latter: If you don't check the checkbox above the HTML, you won't see the whole template.

      AntwortenLöschen
    31. Nun müssen wir nur abwarten, ob unsere Sachen auch geflattrt werden. Gruß aus Berlin, Stephan & Georg
      frequenz9.de

      AntwortenLöschen