Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Support / Documentation

TrackBack Manual

Table of Contents

Movable Type's TrackBack system allows peer-to-peer communication and conversations between weblogs. Imagine that you write about a movie you just saw in an entry on your Movable Type-powered weblog. Another MT weblogger reads your entry, and wants to write an entry referencing your original post. He could just comment on your weblog, but he'd like to keep the post in his own database and host it on his site.

Using TrackBack, the other weblogger can automatically send a ping to your weblog, indicating that he has written an entry referencing your original post. This accomplishes two things:

  1. On your site, you can automatically list all sites that have referenced a particular post, allowing visitors to your site to read the response on the other user's weblog.
  2. It provides a firm, explicit link between his entry and yours, as opposed to an implicit link (like a referrer log) that depends upon outside action (someone clicking on the link to your entry).

You can use TrackBack for more than just communication on particular entries, however. You can also associate TrackBack pings URLs with categories in your weblog. Whenever you post an entry to that category, the URLs you have associated will automatically be notified of your post. This allows remote sites to keep a repository of references to posts all around the web.

For example, if you run a site about Perl, you might want to provide a repository of links to Perl articles on other weblogs. Using TrackBack, you can allow other weblogs to ping a particular category in your own weblog, whenever a new entry is posted that pertains to this category.

These are just examples of TrackBack usage. TrackBack itself is a framework for peer-to-peer communication between weblogs; it can track cross-weblog discussions, it can provide remote content repositories, it can emulate guest authoring, etc. The technical side of TrackBack is very simple: when you want to notify a remote site of your existence, you send a ping to that site. The format of these pings (simple HTTP GET requests) is discussed below. In the Movable Type implementation of TrackBack, we've added password protection to category pings, IP banning, automatic RSS output, and email notification of new pings.

In other words: we want TrackBack to benefit, and to be useful to, more than just Movable Type users. We want to encourage integration of this feature into other weblog tools; that's why we have documented the ping format below and have tried to make the basic framework very simple. Feel free to email us (trackback@movabletype.org) if you have questions.

Setting up TrackBack

If you are a new Movable Type user, the TrackBack tags are included in the default templates, so you are ready to use it as soon as you install Movable Type. You can skip down to Step 5.

If you are an existing MT user, you'll first need to set up your templates to handle TrackBack pings. Start at Step 1.

  1. Create a TrackBack Listing template.
    In List Templates, edit the TrackBack Listing template and initialize it with the template body from the default templates. You can find that here: 
    http://www.movabletype.org/default_templates.shtml#trackback
  2. Update your stylesheet.
    An entry's TrackBack pings are displayed in a popup window similar to that used for listing an entry's comments. The default template that you added in Step 1 uses some CSS styles new to version 2.2. If you are using one of the default styles provided with Movable Type, copy and paste in the updated version from the styles here: 
    http://www.movabletype.org/default_styles.shtml

    If you have a custom stylesheet, you can either customize the TrackBack Listing Template to match your site's styles, or add new CSS styles to your stylesheet for the classes .trackback-url, .trackback-body, and .trackback-post.

  3. Add TrackBack code to your Main Index Template.
    Add the following code in the <script> section of your Main Index Template: 
    function OpenTrackback (c) {
        window.open(c,
                    'trackback',
                    'width=480,height=480,scrollbars=yes,status=yes');
    }

    Now, inside of your <MTEntries> tag, add the following code to display a link to the TrackBack listings for each entry:

    <MTEntryIfAllowPings>
    | <a href="<$MTCGIPath$>mt-tb.cgi?__mode=view&entry_id=<$MTEntryID$>" 
       onclick="OpenTrackback(this.href); return false">TrackBack
    (<$MTEntryTrackbackCount$>)</a>

    </MTEntryIfAllowPings>
  4. Add TrackBack ping data to index and archive templates.
    In your Main Index Template and in your category and date-based archive templates, add the following tag directly after the main <MTEntries> tag: 
    <$MTEntryTrackbackData$>

    Then, in your Individual Entry Archive Template, add this same tag anywhere in the template:

    <$MTEntryTrackbackData$>

    When you rebuild, this will add the necessary information to your public files to allow Movable Type's bookmarklet to parse out entries that allow TrackBack and to grab the ping URL for those entries.

  5. Create a TrackBack-enabled bookmarklet.
    A TrackBack-enabled bookmarklet is just a new version of the standard Movable Type bookmarklet, with one new feature: when you use the bookmarklet to post to your weblog, it will look at the current page in your browser to see if it has any entries that have enabled TrackBack. (It obtains this information using the tag we added in Step 4). If there are any entries, the bookmarklet will allow you to select from the list of TrackBack-enabled entries on that page that you can ping with your new post. When you post your new entry, Movable Type will ping the URL for the appropriate entry automatically, just as if you had entered the URL manually into the URLs to Ping box.

    This simplifies the process of referencing a post on another site using TrackBack.

    If you are already using a bookmarklet, you will just need to recreate it using the same fields you are using now, plus the TrackBack items field. If you are not yet using a bookmarklet, you can create one.

    Go to the Main menu, then click on Set Up Bookmarklets. Follow the instructions to create the new bookmarklet, and be sure to include the TrackBack items field.

  6. That's it!
    Now you're ready to start using the TrackBack system.

    You can test your bookmarklet by going to the following page in your browser:

    http://www.movabletype.org/trackback/

    Once your browser has loaded the page, click on your Movable Type bookmarklet. In the window that opens, you should see a pulldown menu at the top labelled Select a TrackBack entry to ping:. The menu contains a list of all of the TrackBack-enabled entries on the above page.

    If you see the menu, your bookmarklet is working, and you're ready to start using TrackBack!

    If you don't see that line, run mt-check.cgi to determine whether you have LWP::UserAgent installed. That module is required to use TrackBack.

Using TrackBack

TrackBack can be used in two general ways: to communicate between entries on different sites, or to communicate between categories on different sites. In addition, in each of these scenarios you can act as the content producer--where you are posting the entry--or you can act as the content gatherer--where you are gathering a list of entries posted regarding your TrackBack item (whether that be an entry or a category).

  • Entry-to-Entry communication
    As a content gatherer: When you post a new entry that you'd like to allow other users to ping, check the Allow Pings checkbox. The TrackBack URL will then be listed in the ``TrackBack'' popup window, as well as placed on your individual archive page in a <link> tag so that it can be automatically picked up by the Movable Type bookmarklet.

    As a content producer: When you post a new entry and would like to ping an entry on a remote web site, you can either post using the Movable Type bookmarklet you set up above in Step 5 in Setting up TrackBack, or you can manually add the TrackBack ping URL of the remote site into the URLs to Ping box on the new/edit entry screen.

  • Category-to-Category communication
    As a content gatherer: You can designate a category to ``allow pings''. This sets up a TrackBack item for this category so that remote sites will be able to send pings to your site, notifying you of new entries that fit within the category. These pings can then be displayed on your site, allowing you to build a repository of links relating to a particular subject.

    As a content producer: You can associate a list of TrackBack URLs with a category. When you post a new entry into this category on your own site, each of the URLs you have listed will be pinged with information about this new entry.

When a ping is sent to a TrackBack item on your site, in addition to saving the ping in the Movable Type database, the system updates an RSS feed for the TrackBack item. The XML output is saved in a file in your Local Archive Path named ID.xml, where ID is the numeric ID of the TrackBack item.

TrackBack Ping Format

TrackBack uses a REST model for its pings in order to ensure that each TrackBack item has a unique URL (by the numeric ID of the TrackBack item).

  • Sending a ping
    A request is made through HTTP GET to the ping URL, which generally looks like this: 
    http://foo.com/mt/mt-tb.cgi?tb_id=ID

    where ID is the numeric ID of the TrackBack item. The request parameters are added on to the end of that URL, like this:

    http://foo.com/mt/mt-tb.cgi?tb_id=ID&title=TITLE&url=URL

    etc. The possible query parameters are: title (title of the entry); excerpt (an excerpt of the entry, which, if longer than 255 characters, will be cropped to 252 characters and ... added at the end); url (the permalink for the entry); and blog_name (the name of the weblog in which the entry is posted).

    A response is in a simple XML format to enable application-level error detection (HTTP-level errors will be returned as such--for example, if the TrackBack URL points to a non-existent location on the server, a 404 error will be returned from the ping).

    A successful ping will return the following response:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <response>
    <error>0</error>

    </response>

    A failed ping will return the following response:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <response>
    <error>1</error>

    <message>The error message</message>
    </response>

    Applications should, of course, allow for the future addition of fields, if necessary. But the XML structure of the response will remain the same.

  • Retrieving Pings
    To retrieve a list of pings made on a particular TrackBack item, use a URL in this format: 
    http://foo.com/mt/mt-tb.cgi?tb_id=ID&__mode=rss

    where ID is the numeric ID of the TrackBack item.

    The response to this request will either be an error in the same format as returned from the above request, or the list of TrackBack pings for that item in RSS markup, wrapped in <response> tags.

    For example:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <response>
    <error>0</error>

    <rss version="0.91"><channel>
    <title>TrackBack Test</title>
    <link>http://this.is/the/trackback/item/link/</link>
    <description>Description of the TrackBack item</description>
    <language>en-us</language>

    <item>
    <title>TrackBack Demo</title>
    <link>http://this.is/the/permalink/</link>
    <description>Excerpt</description>
    </item>
    </channel>

    </rss></response>
Back

Leave a Comment