wiki:DeveloperGuidelines/Templates

Version 20 (modified by Nuwan Waidyanatha, 8 years ago) ( diff )

--

Templates

Table of Contents

  1. Introduction
  2. Examples
  3. Files
  4. Prepopulate Data
  5. Menus
  6. Theme
  7. Custom Pages
  8. Cascading Templates
  9. References

Introduction

You can set the which template Sahana Eden uses in /models/000_config.py with the line: 

settings.base.template = "default"

Templates allow selecting alternate configuration sets.

This allows a separation between Core Code & Settings/Custom Code.

This helps prevent merge conflicts between different deployment branches & hence reduces the risk of forking.

Examples

See the current templates in Sahana Eden: ​https://github.com/sahana/eden/tree/master/modules/templates

The skeleton template is designed to be copied & renamed to create new templates.

Files

Configuration is done using these files:

  • /modules/templates/000_config.py
  • /modules/templates/default/config.py
  • /modules/templates/<template>/config.py

During the 1st run, 000_config.py is copied to models/

000_config.py includes:

  • FINISHED_EDITING_CONFIG_FILE
  • VERSION
  • machine-specific configuration (Debug, Database, SMTP, API Keys, etc)
  • a setting to define which template folder to run
  • importing of settings from /modules/templates/<template>/config.py
  • optional local overrides to the template's settings

Prepopulate Data

An empty database isn't terribly useful - e.g. maps won't display at all.

Options for how to Prepopulate the database are defined in the template's config.py (but can be overridden in the running 000_config.py):

If you need to tweak your menus of build completely new ones:

Theme

It is possible to develop a custom theme for the look & feel of your system:

Custom Pages

If you wish to add a new custom page without creating a new module:

Cascading Templates

If you wish to inherit the functionality from another template & then make tweaks, you can do this by cascading templates:

modules/templates/MY_TEMPLATE/config.py: 

def config(settings):
    from templates.OTHER_TEMPLATE.config import config as OTHER_config
    OTHER_config(settings)
    settings.base.system_name = T("Other System Name")
    settings.base.system_name_short = T("Other Short System name")

modules/templates/MY_TEMPLATE/controllers.py: 

# Pull a page from another template
from templates.OTHER_TEMPLATE.controllers import other_page
# (This coukld be subclassed if-desired)

# Define your own homepage:
class index():
    ...

modules/templates/MY_TEMPLATE/menus.py: 

from templates.OTHER_TEMPLATE.menus import S3OptionsMenu as OTHEROptionsMenu
class S3OptionsMenu(OTHEROptionsMenu):
    # Override those side menus which are specific.

References

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.