mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-02-04 08:13:38 +00:00
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# 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
|