TurboGears: 20 Minute Wiki Tutorial

# The 20 Minute Wiki

by Kevin Dangoor

There is a printable version of this document.

This is the text version of the "20 Minute Wiki" video (80MB QuickTime). There's actually a little bit more covered in here (the "default" method and the use of validators). The goal of this tutorial is to give an overview of putting together an application with TurboGears. We start from nothing (other than a TurboGears installation) and end up with a simple Wiki.

One note about the video: I pronounced "MochiKit" wrong in a stunning display of not knowing Japanese. The actual pronunciation is MOH-chee.

To go through this tutorial, you'll want:

1. docutils 0.3.9, which is used for formatting. You could get away with not having docutils, but it's not as much fun. `easy_install docutils` should get you what you need.
2. A web browser
3. Your favorite editor
4. Two command line windows (you only need one, but two is nicer.)
5. A database. If you don't have one, your best bet is sqlite 3.2+ with pysqlite 2.0+.

This tutorial doesn't cover Python at all. Check the docs section for more coverage of Python.

## The Quickstart

TurboGears has a command line tool with a few features that will be touched upon in this tutorial. The first is "quickstart", which will get us up and running quickly.

    tg-admin quickstart

You'll be prompted for the name of the project (this is the pretty name that human beings would appreciate), and the name of the package (this is the less-pretty name that Python will like). For this tutorial, we'll be using these values:

    Enter project name: Wiki 20
    Enter package name [wiki20]: wiki20

This creates a few files in a directory tree just below your current directory. Let's go in there and you can take a look around.

    cd wiki20

## Now Serving: Number 1

You may have spotted a file called wiki20-start.py. This is the startup script for the built-in web server. Let's run it!

    python wiki20-start.py

Point your browser at http://localhost:8080/, and you'll see a nice little welcome page with the current time. (If you're on a Mac and have Bonjour bookmarks turned on in Safari, you'll see your new server show up there!)

## That was easy!

Easy indeed. And, if you take a look at the code that the quickstart created, you'll see that there isn't much involved in getting up and running. Two interesting things to look at:

- wiki20/controllers.py has the code that's generating the welcome page. CherryPy makes things very easy... you just write methods and expose them to the web! TurboGears adds the automatic template processing to go from a dictionary of values to HTML for the browser.
- wiki20/templates/welcome.kid is the template you view on the welcome screen. Notice that it's standard XHTML with some simple namespaced attributes? Very designer-friendly. You can even open it directly in your browser!

## Let's make a wiki!

If you're not familiar with a Wiki, you might want to check out the Wikipedia entry. The whole idea is that it's an easily-editable web content system that makes it trivial to link to pages and create new pages.

TurboGears follows the Model-View-Controller paradigm, as do most web frameworks these days. Kid templates are your view, your CherryPy classes are your controllers and basically any object can be your model. In practice, since we're in a database-driven world, your model objects will be SQLObjects.

Since this is all about pages, why don't we go ahead and set up a place to store our pages. TurboGears quickstart gave us a "model.py" module with enough in it to start creating model classes. Here's our Page class:

class Page(SQLObject): pagename=StringCol(alternateID=True, length=30) data=StringCol()

My own personal preference is to work with objects (and not SQL) as much as possible. SQLObject does support creating objects based on the database definition. I prefer to work the other way and create the database definition based on the objects.

For the pagename, we specified alternateID=True, which will guarantee that the column is unique and allow us to easily do searches on pagename. Some databases require the length to be specified on columns you want indexed, we'll just use the arbitrary length of 30 here.

Continue on to page 2