Whetting the Appetite: Make a Wiki in 20 Minutes¶

Setup¶

To go through this tutorial, you’ll need:

1. Python 2.4, 2.5, 2.6 or 2.7. Note that Mac OSX 10.5 (Leopard) comes with Python 2.5 pre-installed.

2. virtualenv. Not that on many Linux based systems you will need to install a Python development package for this to work, such as python-devel or python-dev. In addition, virtualenv is available via most package managers, so can be installed that way.

3. A web browser.

4. Your favorite editor.

5. Two command line windows (you only need one, but two is nicer).

6. Optional: If you’re not aware of it, you may also find the ipython shell to be helpful. It supports attribute tab completion for many objects (which can help you find the method you’re searching for) and can display contextual help if you append a question mark onto the end of an object or method. You can do the same in the standard shell with the dir() and help() functions, but ipython is more convenient. ipython has a number of other convenient features, like dropping into the debugger on an error; take a look at the ipython docs for more information. You can install it with:

   $ easy_install ipython
   

This tutorial doesn’t cover Python at all. Check the Python Documentation page for more coverage of Python.

Virtual Environment¶

The use of a virtual environment is highly recommended. It allows you to segregate your development work from the system, so you can freely experiment without worrying about breaking some other package. The use of it is two steps: Making the directory structure for the virtual environment, and activating it.

$ virtualenv --no-site-packages path/to/virtualenvironment

$ source path/to/virtualenvironment/bin/activate

C:\> path\to\virtualenvironment\bin\activate

Installing the Development Tools¶

Once you have your development environment prepared (using the instructions for making a virtualenv above), installing TurboGears2 itself is extremely easy. Run this command:

$ easy_install -i tg.gy/current/index/ tg.devtools

Wait a few moments as the dependencies are installed and prepared for you.

Quickstart¶

TurboGears2 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 TurboGears2 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]:
Would you prefer mako templates? (yes/[no]): no
Do you need authentication and authorization in this project? ([yes]/no): yes

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:
  tg.devtools#turbogears2  TurboGears 2. Standard Quickstart Template

...etc...

reading manifest file 'Wiki_20.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
writing manifest file 'Wiki_20.egg-info/SOURCES.txt'

This creates a few files in a directory tree just below your current directory. You will notice that the quickstart created a directory without spaces for convenience: project name “Wiki 20” resulted in the directory name “Wiki-20”. Go in there and take a look around:

$ cd Wiki-20

You need to update the dependencies in the file “setup.py”. Currently, it looks like this:

install_requires=[
    "TurboGears2 >= 2.1.1",
    "Genshi",
    "zope.sqlalchemy >= 0.4",
    "repoze.tm2 >= 1.0a5",
	"sqlalchemy",
    "sqlalchemy-migrate",
    "repoze.what-quickstart",
    "repoze.what >= 1.0.8",
    "repoze.what-quickstart",
    "repoze.who-friendlyform >= 1.0.4",
    "repoze.what-pylons >= 1.0",
    "repoze.what.plugins.sql",
    "repoze.who==1.0.19",
    "tgext.admin >= 0.3.9",
    "tw.forms",
    ],

You need to add “docutils” to the list. TurboGears2 does not require docutils, but the wiki we are building does. In addition, if you are using Python 2.4, you need to add “pysqlite”. For this tutorial, we are using the SQLite database, and Python 2.4 does not include support for it out of the box.

Now to be able to run the project you will need to install it and its dependencies. This can be quickly achieved by running from inside the Wiki-20 directory:

$ python setup.py develop

Then paster provides a simple mechanism for running a TurboGears project. Again from the Wiki-20 directory, run this 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. This way you immediately see the results.

Point your browser to localhost:8080 , and you’ll see a nice welcome page. You now have a working project! And you can access the project from within the python/ipython shell by typing:

$ paster shell development.ini

If ipython is installed within your virtual environment, it will be the default shell. Right now, we’re not going to do much with the shell, but you may find other tutorials which use it to add data to the database.

Controller And View¶

If you take a look at the code that quickstart created, you’ll see everything necessary to get up and running. Here, we’ll look at the two files directly involved in displaying this welcome page.

TurboGears follows the Model-View-Controller paradigm (a.k.a. “MVC”), as do most modern web frameworks like Rails, Django, 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 which allow you to create “template” files. These specify how a page will always look, with hooks 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 (see part IV of this book).

Todo

add link to part IV when it is written

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.

class RootController(BaseController):

@expose('wiki20.templates.index')

# -*- coding: utf-8 -*-
"""Main Controller"""

from tg import expose, flash, require, url, request, redirect
from pylons.i18n import ugettext as _, lazy_ugettext as l_
from tgext.admin.tgadminconfig import TGAdminConfig
from tgext.admin.controller import AdminController
from repoze.what import predicates

from wiki20.lib.base import BaseController
from wiki20.model import DBSession, metadata
from wiki20 import model
from wiki20.controllers.secure import SecureController

from wiki20.controllers.error import ErrorController

__all__ = ['RootController']


class RootController(BaseController):
    """
    The root controller for the Wiki-20 application.

    All the other controllers and WSGI applications should be mounted on this
    controller. For example::

        panel = ControlPanelController()
        another_app = AnotherWSGIApplication()

    Keep in mind that WSGI applications shouldn't be mounted directly: They
    must be wrapped around with :class:`tg.controllers.WSGIAppController`.

    """
    secc = SecureController()

    admin = AdminController(model, DBSession, config_type=TGAdminConfig)

    error = ErrorController()

    @expose('wiki20.templates.index')
    def index(self):
        """Handle the front-page."""
        return dict(page='index')

    @expose('wiki20.templates.about')
    def about(self):
        """Handle the 'about' page."""
        return dict(page='about')

    @expose('wiki20.templates.environ')
    def environ(self):
        """This method showcases TG's access to the wsgi environment."""
        return dict(environment=request.environ)

    @expose('wiki20.templates.data')
    @expose('json')
    def data(self, **kw):
        """This method showcases how you can use the same controller for a data page and a display page"""
        return dict(params=kw)

    @expose('wiki20.templates.authentication')
    def auth(self):
        """Display some information about auth* on this application."""
        return dict(page='auth')
    @expose('wiki20.templates.index')
    @require(predicates.has_permission('manage', msg=l_('Only for managers')))
    def manage_permission_only(self, **kw):
        """Illustrate how a page for managers only works."""
        return dict(page='managers stuff')

    @expose('wiki20.templates.index')
    @require(predicates.is_user('editor', msg=l_('Only for the editor')))
    def editor_user_only(self, **kw):
        """Illustrate how a page exclusive for the editor works."""
        return dict(page='editor stuff')

    @expose('wiki20.templates.login')
    def login(self, came_from=url('/')):
        """Start the user login."""
        login_counter = request.environ['repoze.who.logins']
        if login_counter > 0:
            flash(_('Wrong credentials'), 'warning')
        return dict(page='login', login_counter=str(login_counter),
                    came_from=came_from)

    @expose()
    def post_login(self, came_from='/'):
        """
        Redirect the user to the initially requested page on successful
        authentication or redirect her back to the login page if login failed.

        """
        if not request.identity:
            login_counter = request.environ['repoze.who.logins'] + 1
            redirect('/login',
                params=dict(came_from=came_from, __logins=login_counter))
        userid = request.identity['repoze.who.userid']
        flash(_('Welcome back, %s!') % userid)
        redirect(came_from)

    @expose()
    def post_logout(self, came_from=url('/')):
        """
        Redirect the user to the initially requested page on logout and say
        goodbye as well.

        """
        flash(_('We hope to see you soon!'))
        redirect(came_from)

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="www.w3.org/1999/xhtml"
      xmlns:py="genshi.edgewall.org/"
      xmlns:xi="www.w3.org/2001/XInclude">

  <xi:include class="master.html" />

<head>
  <meta content="text/html; charset=UTF-8" http-equiv="content-type" py:replace="''"/>
  <title>Welcome to TurboGears 2.1, standing on the
  shoulders of giants, since 2007</title>
</head>

<body>
    ${sidebar_top()}
  <div id="getting_started">
    <h2>Presentation</h2>
    <p>TurboGears 2 is rapid web application development toolkit designed to make your life easier.</p>
    <ol id="getting_started_steps">
      <li>
        <h3>Code your data model</h3>
        <p> Design your data model, Create the database, and Add some bootstrap data.</p>
      </li>
      <li>
        <h3>Design your URL architecture</h3>
        <p> Decide your URLs, Program your controller methods, Design your
            templates, and place some static files (CSS and/or JavaScript). </p>
      </li>
      <li>
        <h3>Distribute your app</h3>
        <p> Test your source, Generate project documents, Build a distribution.</p>
      </li>
    </ol>
  </div>
  <div />
  <div> Thank you for choosing TurboGears.
  </div>
</body>
</html>

Wiki Model and Database¶

quickstart produced a directory for our model in Wiki-20/wiki20/model/. This directory contains an __init__.py file, which makes that directory name into a python module (so you can use import model).

Since a wiki is basically a linked collection of pages, we’ll define a Page class as the name of our model. Create a new file called page.py in the Wiki-20/wiki20/model/ directory:

# -*- coding: utf-8 -*-
"""Wiki Page module."""

from sqlalchemy import *
from sqlalchemy.orm import mapper, relation
from sqlalchemy import Table, ForeignKey, Column
from sqlalchemy.types import Integer, Text
#from sqlalchemy.orm import relation, backref

from wiki20.model import DeclarativeBase, metadata, DBSession

class Page(DeclarativeBase):
    __tablename__ = 'page'
    
    ##{B:Columns}
    
    id = Column(Integer, primary_key=True)

    pagename = Column(Text, unique=True)
    
    data = Column(Text)
    
    ##{E:Columns}
    
    def __init__(self, pagename, data):
        self.pagename = pagename
        self.data = data

        

In order to easily use our model within the application, modify the Wiki-20/wiki20/model/__init__.py file to add Page to the module. Add the following line at the end of the file:.

from wiki20.model.page import Page

Let’s investigate our model a little more. The metadata object is automatically created by the paste command inside the __init__.py file. It’s a “single point of truth” that keeps all the information necessary to connect to and use the database. It includes the location of the database, connection information and the tables that are in that database. When you pass the metadata object to the various objects in your project they initialize themselves using that metadata.

In this case, the metadata object configures itself using the development.ini file, which we’ll look at in the next section.

The SQLAlchemy DeclarativeBase object defines what a single Python object looks like in the database, and adds any necessary constraints (so, for example, even if your database doesn’t enforce uniqueness, SQLAlchemy will attempt to do so). It provides the metadata object mentioned above, and makes it very easy to define mappings from objects to tables in your database.

An object defined using the DeclarativeBase has a set of class level variables (instead of instance level) which define the columns. As you can see, Column objects are defined in the same way that you define them within a database: name, type, and constraints.

Note that it’s also possible to start with an existing database, but that’s a more advanced topic that we won’t cover in this tutorial. If you would like more information on how to do that, check out sqlautocode.

sqlalchemy.url = sqlite:///%(here)s/devdata.db

page = model.Page("FrontPage", "initial data")
model.DBSession.add(page)

# -*- coding: utf-8 -*-
"""Setup the Wiki-20 application"""

import logging
from tg import config
from wiki20 import model

import transaction


def bootstrap(command, conf, vars<">