03 - Directory Structure

A ZenTools project directory starts life with only three directories inside it: 

zentools-starter/
  assets/
  public_html/
  zentools/

The assets/ directory is a suggested location for all assets related to the project. Store your docs, agreements, graphics, designs, and other assets here.

The public_html/ is the actual DocumentRoot where html files, images, and stylesheets are stored. Additionally, you'll find a special directory named with a single underscore _/ which we call the app's "logic directory". This is where the ZenTools models and controllers are found.

The zentools/ directory is where the actual framework lives. You should rarely if ever need to touch anything in here with the exception of running the ZenTools helper scripts. Just make sure the zentools/ directory is there there and everybody will be happy.

A Bit More Detail

Here's a typical view of the overall directory structure: 

assets/
  doc/
  design/

public_html/
  .htaccess
  _/
    config.py
    controllers.py
    filters.py
    messages.py
    models.py
    zentools.log
  css/
  en/
    _layout.html
    index.html
    some-other-page.html
  images/
  js/

zentools/
  doc/
  extra/
  lib/
  script/
  tmp/

In the public_html/ directory, there are some familiar friends: Typical directories for css/, images/, and js/ along with some .html files in the en/ directory. This is a language directory (we explore ZenTools' language handling in a later section). However, it's worth noting here that only HTML templates are contained within the language directories. Directories such as images/, css/, and the logic directory _/ are considered to be non-language specific and are therefore located outside the language directories.

As stated above, you don't usually have to worry about the zentools/ directory much just so long as it's there and the .htaccess file points to it.

The basic philosophy in this directory structure is to totally separate the site-specific code from the framework code. This is neatly accomplished by simply putting all of the ZenTools framework code off to the side in its own directory and putting pretty much everything else inside the DocumentRoot where most of it naturally belongs anyway.

Extra Apps

If your website includes some loose logic here and there such as the occasional contact form or whatever, then you'll probably be happy to just consider the entire site to be your "application". In that case, the logic directory shown above is all you'll need. But if you'd like to develop an application within your site, you can do that too. An application in ZenTools is a self-contained directory of files inside your public_html/ directory. So what makes it an app? It's got its own logic directory.

Here's an example of what a blog application might look like: 

blog/
  _/
    controllers.py
    messages.py
    models.py
  css/
  en/
    index.html
    posts.html
    article.html
    ...etc
  images/
  js/

Notice that a self-contained application is entirely self-contained. It even has its own css/, images/ and js/ directories. It also has its own language directories. The idea here is that by keeping everything needed for the app inside a single directory, we're able to reuse apps in other projects remarkably easily. We literally need only to drag the app into some other site and run the syncdb script to create the necessary tables in our existing database. The imported app will naturally use the site's default _layout.html and stylesheets which means that ZenTools apps very elegantly fit right into an existing project inheriting the host website's overall look and feel.

Quick Recap

You start with three directories at the top level: assets/, public_html/, and zentools/. Use assets to store your PSDs, Docs, etc. The public_html/ directory is where the site lives -- including the logic directory _/. And the zentools/ directory contains the actual framework and helper scripts. You can also have apps within a project which have their own logic directory.

Got all that?

Next: 04 - HTML Templates