taga.licio.us : a way to integrate del.icio.us « planetOzh

I found a lot of ways and hacks to integrate your delicious links into a page, but I wanted to fetch all links for a given set of tags, not just mine, so I wrote my own hack : introducing taga.licio.us, yet another del.icio.us php hack !

Taga.licio.us is a tag filter for del.icio.us : it produces a page with links from selected tags, allows to integrate del.icio.us links for one or more tags into an existing page, limited to a specified "freshness" (links of the day ? of the hour ?), and comes with gazillions of options. If you are a WordPress user, it is also able to directly post into your database to, say, run the script daily at fixed hour and print links on a given subject right into your blog.

What for ?

I personnaly use del.icio.us as a starter for my click & browse session : on a given subject, ie tag, I find it a nice collection of more or less fresh links and I often find interesting sites. So I'm using the script as a delicious "digest" : filter all the unwanted tags off, display just what I want to read about and start surfing from there.

You can also integrate the resulting page into an existing one. Say for example you run a site about mp3 and games : you could print daily del.icio.us links on this subject. Effortless fresh content everyday :-P

Live example

Before we go on with my usual 40 page documentation, let's see the kind of results the script can output :

• One day old webdesign and css links (default tags as specified in the script)
• One day old blog links (tag specified in the query string)
• One day old php and python links (tags specified in the query string)

Etc … Easy digest of subjects that interest you, to browse from or to integrate into a page.

Ready for the installation guide & manual ? Let's go.

RSS PHP Parser of the Century Award : MagpieRSS

This hack is just a humble user of Magpier RSS, a PHP parser for RSS feeds that is truely powerful. So, first of all, you need to install it on your server. Just download the latest archive, unpack it anywhere on your site and you're done.

If it is possible, I'd recommend putting it beneath your document root (~/htdocs) along with all your shared libraries and stuff. But if not, really anywhere will do, and should someone access a file in their browser, it will have no output and no effect, so don't be afraid.

Get the script : taga.licio.us

The script comes in two flavors : one for anyone willing to integrate del.icio.us links into a php page, and one for WordPress users with a few extra abilities detailed below.

• Standard version :
  • delicious-tagalicious.php (syntax highlited, cut 'n paste into a blank file)
  • delicious-tagalicious.txt (raw text, save as .php)
• WordPress version :
  • wp-delicious-tagalicious.php (syntax highlited, cut 'n paste into a blank file)
  • wp-delicious-tagalicious.txt (raw text, save as .php)

Note for WordPress users: although it may look like a plugin, this is not a plugin. This is a standalone script, don't put it in your wp-content/plugins directory or, to quote a source you may have read before, the sky will fall on your head.

Configure the script

Anyone could just stop reading now, since reading the script itself will be probably enough : as usual my "work" is heavily commented and options are detailed to death. I'm just posting everything here for further reference.

First are variables you'll find in both versions. WordPress specific ones will be found below in a, guess what, WordPress section.

Magpie stuff

require_once '/home/you/magpierss/rss_fetch.inc';
This is the physical path to your Magpie copy.
Note for windows users : put path like 'C:/myweb/magpierss/rss_fecth.inc' (regular slashes, not antislashes)

define('MAGPIE_CACHE_ON', 1);
Use MagpieRSS built-in cache feature : this is mandatory for the sake of courtesy. You don't want to fetch a file everytime someone reads your blog, so this parameter tells Magpie to use a cached copy.
To do so, you have to create a directory where your taga.licio.us script is, named "cache", and chmoded to something writable (0777 will do fine)
Note: If you want to cache RSS feeds in another directory, use the constant MAGPIE_CACHE_DIR (for more information, read the comments at the beginning of rss_fetch.inc in your Magpie directory)

define('MAGPIE_CACHE_AGE',3600);
Number of seconds before a file is considered old and you fetch a fresh one. One hour seems fair if you intend to integrate the output into your blog.

Fetching del.icio.us options

Now onto the real core of the options. As usual, all variables (and functions) start with "wp_ozh_deli", to prevent cross reference with another script.

$wp_ozh_deli_param['tags'] = "webdesign css";
Value : a space separated list of tags
Examples : 'mp3' for all links tagged with mp3, 'php python' for all links tagged with php, and all links tagged with python.
This can be overridden by the query string (?tags=php) as on the live examples above.
Note : Although you can actually read on del.icio.us links with 2 or more tags (blog+css+design for example) the associated feed is not correct. So passing a parameter like 'css+blog' won't break the script, but won't produce the wanted result.

$wp_ozh_deli_param['freshness'] = 86400;
Value : an integer, number of seconds for a link to be considered printable.
Typically, if you fetch the script every 24 hours using a cronjob, set it to 86400. A few reminders : 86400s = 24h, 43200s = 12h, 21600 = 6h, 3600 = 1h.

$wp_ozh_deli_param['maxitems'] = 0;
Value : an integer, maximum number of links per feed.
This setting overrides freshness is applicable. Set to 0 (zero) if you don't want to limit : in such a case, you may hit the del.icio.us feed number of items as a limit, set to 30.

Output options

Next variable has a multiline syntax, be careful when editing. Starts with a ' (single quote) and ends accordingly

$wp_ozh_deli_param['post']

Value : some html code.
Note the use of 3 "templates variables" :

• %%COUNT%% will be replaced by the number of links fetched
• %%TAGS%% will be replaced by the list of tags you picked in a readable format, for example : "mp3, music and audio"
• %%LINKS%% will be replaced by the links, as defined by the next parameter

$wp_ozh_deli_param['pattern']

Value : some html code.
Each link fetched will replace the %%LINKS%% template with this pattern, also using a set of templates :

• %%url%% will be replaced by link url
• %%description%% will be replaced by link description
• %%time%% will be replaced by the time, according to $wp_ozh_deli_param['time_display'] as explained below
• %%tags%% will be replaced by naked gurlz. Errrr, I mean, by the list of tags of the link. Just wanted to check if someone is reading.

$wp_ozh_deli_param['time_display'] = 'elapsed';
Value : 'time' or 'elapsed'

• 'time' : prints at what time the link was posted on delicious, e.g. "2004-09-23 05:36" (see next parameter for Date pattern)
• 'elapsed' : print the time elapsed since the link was posted on delicious, e.g. "5h40 ago"

$wp_ozh_deli_param['time_pattern'] = 'Y-m-d H:i';
Value : a string using the same syntax as the PHP date() function.
If previous parameter set to 'time', this will control the output format of the date. For example, a value of 'Y-m-d H:i' will print "2004-09-23 05:36" (a la del.icio.us)

$wp_ozh_deli_param['time_offset'] = 0;
Value : an integer, time offset between del.icio.us server and your server (not your computer)
Example : 3 means del.icio.us prints "15:12:23" when it's "12:12:23" on your server
Example : -2 means del.icio.us prints "15:12:23" when it's "17:12:23" on your server
Newbie tip: To check the time on your server, put the next line in a new file, upload on your server and read it with your browser :

$wp_ozh_deli_param['skip_empty'] = 0;
Value : 1 or 0.
If If your freshness & tag filter select no link, what to do ? Set to 1 not to print anything, set to 0 to print something anyway, as defined by the next parameter.

$wp_ozh_deli_param['no_entry'] = 'No entry today, sorry !';
Value: a string.
If the previous parameter is set to 0 (ie post something even if there is no link matching criteria on del.icio.us, this message will be printed in replacement of the links (%%LINKS%% tag in the output pattern)

WordPress Specific options

require_once './wp-blog-header.php';
This one is pretty usual. If you move taga.licio.us somewhere from your wordpress root dir, be sure to edit this accordingly.

$wp_ozh_deli_param['more'] = 5;
Value : an integer.
Number of posts after which to place a "Read more…" break when displayed in front page

$wp_ozh_deli_param['insert_sql'] = 0;
Value : 1 or 0.
Defines if you want the result to be injected as a post in your WordPress database. Default is 0 so you won't mess with it until you're done with editing :)

$wp_ozh_deli_param['userid'] = 1;
Value : an integer
This is the User ID to post in. Usually yours, the admin's. If unsure, check http://yourblog.com/wp-admin/users.php and look for yours.

$wp_ozh_deli_param['category'] = 1;
Value : an integer
Category id to put your tag.ali.cio.us links in. If unsure, check http://yourblog.com/wp-admin/categories.php

$wp_ozh_deli_param['allowcomments'] = 'open';
Value : 'open' or 'closed'
Allow comments on the posts ? Of course you want to. Otherwise, how would spammers get a life ? :-P

$wp_ozh_deli_param['allowpings'] = 'open';
Value : 'open' or 'closed'

$wp_ozh_deli_param['posttitle'] = 'Dai.ly tag.ali.cio.us';
Value : a string, title for your posts.

$wp_ozh_deli_param['postname'] = 'daily-tagalicious';
Value : a string, defind the "post slug" as used in permalinks (/archives/2004/10/04/daily-tagalicious/)

$wp_ozh_deli_param['excerpt'] = 'Daily load of links from del.icio.us on: ' . $wp_ozh_deli_param['tags'];
Value : a string, defining the post excerpt.

Important note for WordPress users

If you want to use the posting feature, for example at fixed hours with a cronjob, first rename the file to something secret and personnal. You don't want any lamer in the internet come to your site and reload wp-delicious-tagalicious.php till your MySQL base dies.

Integrating output into an existing page

This is done as usual with the include php function. For example, if you rename the script to "tagalicious.php", put this into your page :

Known bugs

I am not too sure about how it handles utf-8. I've seen a lot of links with broken utf-8 on del.icio.us itself, so most of the weird content you'll fetch will be original content. I've been told it also depends on the version of your Mysql installation. Sorry, couldn't test this a lot. Anyway, it should be ok 99% of the time.

The feeds on del.icio.us are not always up to date. It seems they are updating them every 5 minutes or so, rather than generating them on the fly. Don't panic if your output misses one or two fresh links.

Wow

That was another long documentation, wasn't it ? Of course, I'm looking for celebrity feedback, so now go play with taga.licio.us !