02 - Quick Start

ZenTools requires no installation. You just need to make sure your system is running Mod_Python and a few other basic requirements, download a zentools-starter tarball, and run the init script. Here's the process in more detail:

(1) Make sure your system is ZenTools ready

Minimum Requirements:

Unix-like OS (BSD, Linux, OS X, Unix)
Python 2.4 - 2.6
Apache 2
Mod_Python 3.1
Python_MySQL
MySQL 4.1

(2) Make you're using Apache virtual hosts for dev

If you're using a 'nix OS, there's a good chance you're running Apache with virtual hosts to serve your development sites. If not, you should really consider doing so! It's not hard and it really makes the development process a lot slicker. There are plenty of tutorials around the web for setting up a local web server with virtual hosts for website development so we won't re-invent the wheel by re-describing it here. But that's the first step. ZenTools relies on each project having it's own hostname, for example: my-new-project.devbox.

(3) Get the "starter" tarball

If you haven't already, download the ZenTools Starter tarball to your development projects directory. Let's assume that directory is located at /projects.

Decompress the tarball and rename your project directory:

cd /projects
tar zxvf starter.tgz
mv zentools-starter my-awesome-website
cd my-awesome-website
zentools/script/init

(4) Add the VHOST and /etc/hosts

Add an entry for the project to your Apache virtual hosts and also add a host entry to your /etc/hosts file. If you're unsure of how to do this, please find a tutorial on using virtual hosts for web development for your operating system. Don't forget to restart apache after adding the vhost.

You should now be able to view the boilerplate site in your browser.

(5) Adding a new page

One of the central themes of ZenTools is to stay out of your way. If you want to add a simple page of static content to your site, you can just do it as you normally would. Make a file in your docroot called new-file.html for example. Then browse to that file using a url like: my-project.devbox/new-file

Don't forget to omit the ".html" when browsing to your file!

The new file will appear as the content of your _layout.html. If you look at the source code of _layout.html, you'll find a <div> block with id="content". By default, that block will be populated with the file which is being wrapped in the layout. Note that you can easily add alternate layouts or even choose to not use a layout at all (useful for pop-up windows for example). The standard way to define which layout your page will use is to set a "Page Setting"".

(6) Using page settings

Very often, it's necessary to alter some aspects of the layout on a page by page basis. For example, you typically want the <title> tag to reflect the current page being viewed. It's always possible to get at these things from the controller of course. But for common settings such as the title or the layout, you can just set those at the top of the page using very natural syntax like this:

new-file.html

Title: My New File Using ZenTools!
Layout: _alt-layout.html

<h1>New File</h1>

<p>This is my new file using ZenTools.</p>

(7) Adding some controller logic

Page settings are very useful for a small set of common tasks. But if you really need to apply some logic or template formatting to a page, that's what the controllers file is for. You'll find the site's main controllers file in www/_/. The _/ directory is where the logic files live. Among them, you'll find one called controllers.py. Open that and add a method under the frontend class like this:

_/controllers.py

def new_file():
    html.replace_with("Hello from the controller!")

When you refresh the page, you should see that the whole page has been replaced with the message from the controller.

Now instead of replacing the entire page, let's just replace the content of the page. As mentioned before, the main content of the page is always wrapped in a div with id="content". So we can target that element and replace its contents like this:

def new_file():
    html.content = "Hello from the controller!"

What if we just want to replace the <h1> tag within the "content" element?

def new_file():
    html.content['h1'] = "Hello from the controller!"

Taking it one step further, let's also add a style attribute to the <h1> tag.

def new_file():
    html.content['h1'] = "Hello from the controller!"
    html.content['h1'].style = "color:green"

So controllers have complete access to the entire HTML document. And this is the secret sauce that allows us to keep our templates very clean and simple, pure and valid HTML with no ugly template code to muddy it up. But of course you can do a lot more than just tweak the template. Let's look at models first, then we'll use controllers to put it all together.

Special note for Python Newbies:

Python uses whitespace to delimit code blocks. This means that when editing any file in ZenTools which has a .py extension, you'll need to take care to keep your indentation levels consistent. You can choose tabs or spaces as long as you stay consistent. The ZenTools convention is to use 4 spaces for each level of indentation in Python files (consistent with PEP8). Note that HTML templates are not Python files so whitespace is not a concern there.

(8) Creating a model

Models let you deal with data from your database in a really convenient object-oriented way. They also help automate some of the MySQL tedium with automated table creation and form validation among other things.

To create a model, open _/models.py (that's the same directory as controllers.py). Let's say we want to add a model and a corresponding MySQL table to store records for our friends.

class Friend(Model):
    first_name = 'char'
    last_name  = 'char'
    age        = 'int:opt'
    _order     = 'age desc'

Now fire up a Terminal shell, cd into your project directory and sync your db:

zentools/script/syncdb

ZenTools just created your MySQL database and table for you.

(9) Working with the ZenTools shell

While still in the Terminal, you can also interact directly with your website and applications from the shell.

zentools/script/shell

For example, we can create a new Friend object like this:

>>> friend = models.Friend()
>>> friend.first_name = 'Bob'
>>> friend.last_name = 'Barker'
>>> friend.age = 145
>>> friend.save()

Don't worry if you didn't absorb all of that. This is just a 100 mph tour of some ZenTools highlights. The gaps will get filled in as you continue through the next sections starting with a birds-eye view of the directory structure.

Next: 03 - Directory Structure

_/ ZenTools Project

Table of Contents