Well, one of the things that boggled my mind (and there’s a couple of ‘em) with this whole Typo thing was the Amazon sidebar, which supposedly did wonderous things. Billed as “Capable of displaying books referenced in your articles”, I was excited to see what the heck that means, and (some might say more importantly) how to do it.
As usual, documentation was found to be severely lacking.
I hate to think that developers would take for granted that people would somehow “just know” how the syntax for this works (or even that there needs to be syntax). In fact, I’m going to give them the benefit of the doubt right away and say that it must be in development, and that documentation is no doubt on the way, or exists somewhere obscure. Yeah. I should also note that if you’ve managed to get Typo running (no mean feat), then there’s a good chance that you’re technically adept enough to figure all this out.
So I’m writing this to help out The Not-So-Darned-Technical Guy. That guy who’s just technical enough to hammer his way through installing and getting Typo running, but is banging his head against a wall figuring out these niggling little details that everyone conveniently forgets to mention. Hopefully it’ll help somebody out there.
First and foremost, here’s an article that also addresses the issue. Be warned, while very thorough and well-written (the whole RubyNoob site is full of some really good articles), this particular article made precious little sense to the likes of me, but it might be super useful to anyone who’s been a software developer for the last decade of their life. The last part of the article is really the most useful to The Rest of Us, and it only takes a tiny bit of interpretation.
This is the controller for the Amazon post-processing text filter. Using this filter allows you to enter links to amazon items with an href like this: href=”amazon:097669400X” and turns that into something like this: href=”http://www.amazon.com/exec/obidos/ASIN/097669400X/scottstuff-20.”
But wait, I’m getting a little ahead of myself. The first thing to do (before we interpret that little snippet) is to actually activate the “Amazon Text Filter”. There’s a few ways to do this, so first I’ll outline the way I did it, and why.
In the Typo administration area, click on that link at the end that says “Filters”. This’ll take you to the magical text-filters area, and shows a list of the current text-filters. What’s all this? Explanation coming right up!
A text-filter (just being thorough here) is (basically) a big funnel that all your text gets thrown into and emerges formatted a certain way (this depends, of course, on which filter you use.) The filter will interpret little bits of code that you use as stand-ins for more complex bits of code and replace them accordingly. This sounds confusing, doesn’t it? Hm. Think of it this way: you have a car. You put 4 hubs on it, one at each end of the axles. You push it through a filter, and when it comes out, it’ll have tires, brakes, cables, bearings, and all the stuff that wheels on a car have. In much the same way, a filter will take, for example, a very simple bit of code, and when it is published, that filter will replace those simple bits with much more complex, functional bits. This saves a lot of time and energy that you can then use for more useful tasks. Like writing articles.
So, back to the task at hand. You’re sitting in the “Filters” area of the Typo administration. You should see a list of filters, including one called “Markdown”. Click on the “Edit” button on that line. Why Markdown? Well, because I really like it and it’s easy to use. John Gruber, the man behind Daring Fireball, has written this excellent guide to Markdown. But don’t fret, this method works for all the different filter types, so really, you can click “Edit” on whichever filter you use (as long as you’re using a filter, of course) and follow along.
About halfway down the page you’ll see a checkbox next to the text “Amazon”, followed by a short description. Check that box. You’re not done yet, though – near the bottom is a textbox where you have to enter your Amazon Associate ID. I’m not actually sure if that’s 100% necessary – you may be able to reference Amazon books without that ID – but if you *do* have an ID in there, you’ll get credit for any sales originating from your site. It’s not much (of course), but hey, every little bit counts. If you have an Associate ID, enter it here. If you don’t, here’s a link to Amazon so you can get one. It’s free, so go get one.
Once you’ve entered your ID, click the “Store” button. Congratulations, you’ve enabled Amazon filtering. Now comes the fun part – how to use it!
Remember that paragraph waaay at the beginning of the article? It had two very important bits of information – let’s revisit it:
an href like this: href=”amazon:097669400X” and turns that into something like this: href=”http://www.amazon.com/exec/obidos/ASIN/097669400X/scottstuff-20.”
Depending on which filter we’re using, this can be interpreted in a few different ways. Here’s a couple of examples (first standard HTML and then Markdown):
[Ruby On Rails](amazon:097669400X)
Either of these will produce a link that, when published, will link to Amazon with all the correct additional numbers needed. That’s pretty cool, right? Of course it is. And even cooler, the sidebar has now picked up the reference and is displaying information direct from Amazon.
Wait, wait, what’s that number? How do I find it? It’s true: when you go to Amazon and look up a book to reference, you get a bewildering amount of numbers and letters. For example, the book we just referenced has the following URL:
The important number is the one after “product” (in this case, “097669400X”). That’s the ASIN number, and the one you have to use in your filter. Look up any book in Amazon, and you’ll find that number in the same spot. Copy and paste it in, and you should see results.
With that information, you’re done! Kick back, relax, and enjoy the fact that you didn’t have to set a single breakpoint in the Rails code to figure it out. 😉
Pretty sexy, ain’t it?