Quickstarting your project

TurboGears provides a suite of tools for working with projects by adding several commands to the Python command line tool paster. A few will be touched upon in this tutorial. (Check the Command Line Reference for a full listing.) The first tool you’ll need is quickstart which initializes a TurboGears project. Go to a command line window and run the following command:

$ paster 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). Here’s what our choices for this tutorial look like:

$ paster quickstart
Enter project name: Wiki 20
Enter package name [wiki20]: wiki20
Do you need authentication and authorization in this project? [yes] no

We recommend you use the names given here: this documentation looks for files in directories based on these names.

Now paster will spit out a bunch of stuff:

Selected and implied templates:
  TurboGears2#turbogears2
  TurboGears 2.0 Template

...etc...

running compile_catalog
1 of 1 messages (100%) translated in 'wiki20/i18n/ru/LC_MESSAGES/wiki20.po'
compiling catalog 'wiki20/i18n/ru/LC_MESSAGES/wiki20.po' to 'wiki20/i18n/ru/LC_MESSAGES/wiki20.mo'

This creates a directory tree Wiki-20 just below your current directory. We have just one more stage of installation to complete:

$ cd Wiki-20
$ python setup.py develop

This will emit some output, and hopefully finish with success:

(tg2env)localhost~/python/turbogears/tg2env/Wiki-20$ python setup.py develop
running develop
running egg_info
writing requirements to Wiki_20.egg-info/requires.txt
writing Wiki_20.egg-info/PKG-INFO
writing top-level names to Wiki_20.egg-info/top_level.txt
writing dependency_links to Wiki_20.egg-info/dependency_links.txt
writing entry points to Wiki_20.egg-info/entry_points.txt
writing paster_plugins to Wiki_20.egg-info/paster_plugins.txt
reading manifest file 'Wiki_20.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
writing manifest file 'Wiki_20.egg-info/SOURCES.txt'
running build_ext
Creating /home/user/python/turbogears/tg2env/lib/python2.5/site-packages/Wiki-20.egg-link (link to .)
Adding Wiki-20 0.1dev to easy-install.pth file

Installed /home/user/python/turbogears/tg2env/Wiki-20
Processing dependencies for Wiki-20==0.1dev
Searching for repoze.tm2==1.0a4
Best match: repoze.tm2 1.0a4
Processing repoze.tm2-1.0a4-py2.5.egg
repoze.tm2 1.0a4 is already the active version in easy-install.pth
...
...
Finished processing dependencies for Wiki-20==0.1dev

Now we’re ready to start!

Structure of a Turbogears Project

The current directory Wiki-20 is the root directory of your project.

All imports of project code are made relative to this directory, and all html templates are called from this directory too. All files we discuss will be relative to this root directory.

Some of the files you’ll find in your root directory after you’ve quickstarted a new project include:

../../_images/quickstart_tree.png

The main subdirectories we’ll be concerned with are model, templates and controllers.

TurboGears follows the Model-View-Controller paradigm (a.k.a. “MVC”), as do most modern web frameworks like Rails, Cake, Struts, etc.

  • Model: For a web application, the “model” refers to the way the data is stored. In theory, any object can be your model. In practice, since we’re in a database-driven world, your model will be based on a relational database. By default TurboGears 2 uses the powerful, flexible, and relatively easy-to-use SQLAlchemy object relational mapper to build your model and to talk to your database. We’ll look at this in a later section.
  • View: To minimize duplication of effort, web frameworks use templating engines that allow you to create “template” files. These specify how a page will look, with hooks or variables where the templating engine can substitute information provided by your web application. TurboGears 2’s default templating engine is Genshi, although several other engines are supported out of the box and can be configured in your config/app_cfg.py file.
  • Controller: The controller is the way that you tell your web application how to respond to events that arrive on the server. In a web application, an “event” usually means “visiting a page” or “pressing a submit button” and the response to an event usually consists of executing some code and displaying a new page.
MVC Interface Turbogears Defaults files you’ll be editing
Models Database SQLAlchemy wiki20/model/*.py
Views Webpage Genshi wiki20/templates/*.html
Controllers User/Content Turbogears wiki20/controllers/root.py

Starting the server

The file development.ini that paster has written to your root directory contains a default setup, including connection to an sqlite file database. You’re free to change your settings to use another database, host url, etc. - edit as you please.

paster provides a simple mechanism for running a TurboGears project. From inside the Wiki-20 directory, the root directory of your project, run the command:

$ paster serve --reload development.ini

The --reload flag means that changes that you make in the project will automatically cause the server to restart itself, loading the changes. This way you immediately see updated results.

You can access your models from within the python/ipython shell by typing:

$ paster shell development.ini

from your root directory. If ipython is installed within your virtual environment, it will be the default python shell.

You now have a working project! Point your browser to http://localhost:8080, and you’ll see a nice welcome page:

../../_images/index.png

There are some links on this page to TurboGears documentation. Spend some time exploring what’s there.


Now we’ll look at the two files directly involved in displaying this welcome page:

  1. wiki20/controllers/root.py – what dynamic content appears on the page
  2. wiki20/templates/index.html – how the page appears

Table Of Contents

Previous topic

Setup

Next topic

Index Page

This Page