Basic Moves

Table of Contents

Here are some basic moves you need to play with TurboGears.

Wetting your feet

If you take a look at the code that quickstart created, you’ll see that there isn’t much involved in getting up and running.

In particular, you’ll want to check out the files directly involved in displaying this welcome page:

  • start-tutorial.py is an implicit starting script that you could add your starting operations here.
  • The system configuration is laid on dev.cfg and prod.cfg for development and production configuration respectively.

Note

To change the port used by the built-in web server, edit dev.cfg to change the default server port:

server.socket_port = 8080

Note

To use the default ‘production’ configuration, you could specify which configuration file to use when starting the server:

$ python start-tutorial.py prod.cfg
  • tutorial/templates/welcome.html is the template you view on the welcome screen. It’s a standard XHTML file with some simple namespaced attributes. You can even preview it directly by open it in your browser! Very designer-friendly.
  • tutorial/controllers.py is responsible to generate the welcome page.

Let’s say ‘Hello World’ to them respectively.

Say Hello to the Template

To start adding and modifying template, open tutorial/templates/welcome.html.

If we replace the HTML body in welcome.html with the code below, we’ll have the TurboGears equivalent of a ‘Hello, world’ application:

....
<body>
 Hello, world!
</body>
....

Start the server again and browse to http://localhost:8080. You should see “Hello, world!” appeared in your web browser.

Say Hello to the Controller

Controllers are your way of specifying what code gets executed when an incoming request to your web service is received.

To map request URLs and parameters to Python functions, TurboGears uses a module called CherryPy.

You just write methods and expose them to the web with a @expose()`` decorator. (The decorator is a powerful element in TurboGears, you’ll learn more of them).

To start adding and modifying controllers, open tutorial/controllers.py.

If we replace the Root class in controllers.py with the code below, we have the TurboGears equivalent of a ‘Hello, world’ application:

class Root(controllers.RootController):
    @turbogears.expose()
    def index(self):
        return "Hello, world!"

Start the server again and browse to http://localhost:8080. You should see “Hello, world!” in plaintext.

Combine Controller with Templates

So far we’ve been returning plaintext for every incoming request. But you might have noticed how the default welcome page work. Let’s plug real templates into the controllers.

TurboGears uses the Genshi templating system by deault for controlling dynamic content in your markup.

For each page on your site, you could give each of them the corresponding template in your controllers. You could specifying the template argument with``@expose`` decorator:

@expose(template="tutorial.templates.welcome")
def index(self):
    ...

Template arguments are used to pass variables and other dynamic content to the template.

You can pass template arguments from your controllers by returning a dictionary whose keys are the names by which the variables will be accessible in the template:

@expose(template="tutorial.templates.welcome")
def index(self):
    records = ['iterable', 'items']
    return dict(records = records)

Not every template has dynamic content and therefore may not need arguments. In that case, just return an empty dictionary:

@expose(template="tutorial.templates.welcome")
def index(self):
    return dict()

To create more skeletons for your templates, just copy the default welcome.html template that was generated when your project was created.