diff options
Diffstat (limited to 'doc/themes.mdwn')
-rw-r--r-- | doc/themes.mdwn | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/doc/themes.mdwn b/doc/themes.mdwn new file mode 100644 index 0000000..3546182 --- /dev/null +++ b/doc/themes.mdwn @@ -0,0 +1,59 @@ +# Themes and Templates + +The visual look and feel of the front end is described in theme files +while <a href="http://cheetahtemplate.org">Cheetah templates</a> +handle layout. + +## Themes + +Themes are stored in `/themes`. Themes consist entirely of static +files (e.g. css, images and javascript) and templates. The default or +active theme is linked from `/static/default` and `templates/default`. +If your theme needs to change anything other than these items, you'll +need a module (perhaps you'll need both). + +There is not currently any support for dynamically choosing a theme at +runtime, but it is theoretically possible. + +## Templates + +Plinth uses the Cheetah templating system. Templates are stored in +`/templates`. Template requirements are not specified. + +TODO: formalize the template spec so template writers know what they need to implement and where they can deviate. + +In this section, I'll attempt to document some of the assumptions the +program has about templates. The goal is that if you write a tempate +that implements the spec, it should work just fine. + +### The Template Stack +The template is a hierarchical stack, where some templates extend on +others. At the base of this stack is `base.tmpl`. It should specify +variables as blocks (rather than using the $ notation). This allows +other templates to easily override the base template. + +Next up is the `page.tmpl`. It extends `base.tmpl` and simply +replaces all the blocks with interpolable variables. Most of the +time, `page.tmpl` is what you will actually use to create pages. + +`err.tmpl` builds on top of `page.tmpl` by adding some decoration to +the title field. + +### Layout + +Plinth expects a `main` block. This is where the +meat of the content goes. It is the center pain in the default +layout. There is a `title` block that the program will fill with text +describing the current page. `sidebar_left` contains the submenu +navigation menu, and `sidebar_right` is where we put all short text +that helps the admin fill out forms. They don't have to be sidebars, +and they don't have to go on the left and right. + +It is possible to override the `footer`, but I haven't yet found a +reason to do so. + +## Cheetah + +This section is for Cheetah hints that are especially useful in this context. + +TODO: add Cheetah hints |