...

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