Changes between Initial Version and Version 1 of DeveloperGuidelines/Templates/Migration


Ignore:
Timestamp:
01/05/15 08:56:21 (7 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/Templates/Migration

    v1 v1  
     1= Migration of Templates to modules/templates =
     2[[TOC]]
     3
     4== Introduction ==
     5
     6We have changed the way templates are handled:
     7
     8  * templates now live in modules/templates (formerly private/templates)
     9  * the template's config.py is now a Python module instead of a Python script and will be imported rather than executed
     10  * the settings in config.py have been moved into a function config()
     11
     12This has a couple of advantages:
     13
     14  * being in the modules-path, templates can be imported and do not need to be re-compiled and executed on every request
     15  * templates are treated as Python packages so that config.py can import template-specific modules
     16  * config.py can now define classes and functions without risk for memory leaks
     17  * templates can share common modules via regular imports
     18
     19We have implemented a fallback logic for legacy templates, to give downstream projects some time to migrate. We highly recommend to migrate any legacy templates from private/templates to modules/templates. This page gives instructions how to do this.
     20
     21== Moving to modules/templates ==
     22
     23Copy the entire template folder to modules/templates.
     24
     25== Refactoring config.py ==
     26
     27Re-structure config.py so that all settings-assignment are inside a function config():
     28
     29Old config.py:
     30{{{
     31# -*- coding: utf-8 -*-
     32
     33try:
     34    # Python 2.7
     35    from collections import OrderedDict
     36except:
     37    # Python 2.6
     38    from gluon.contrib.simplejson.ordered_dict import OrderedDict
     39
     40from gluon import current
     41from gluon.storage import Storage
     42
     43T = current.T
     44settings = current.deployment_settings
     45
     46"""
     47    Template settings
     48
     49    All settings which are to configure a specific template are located here
     50
     51    Deployers should ideally not need to edit any other files outside of their template folder
     52"""
     53
     54settings.base.system_name = "Example"
     55settings.base.system_name_short = "Example"
     56
     57# PrePopulate data
     58settings.base.prepopulate = ("default/users",)
     59...
     60}}}
     61
     62New config.py:
     63{{{
     64# -*- coding: utf-8 -*-
     65
     66try:
     67    # Python 2.7
     68    from collections import OrderedDict
     69except:
     70    # Python 2.6
     71    from gluon.contrib.simplejson.ordered_dict import OrderedDict
     72
     73from gluon import current
     74from gluon.storage import Storage
     75
     76def config(settings):
     77    """
     78        Template settings
     79
     80        All settings which are to configure a specific template are located here
     81
     82        Deployers should ideally not need to edit any other files outside of their template folder
     83    """
     84
     85    T = current.T
     86
     87    settings.base.system_name = "Example"
     88    settings.base.system_name_short = "Example"
     89
     90    # PrePopulate data
     91    settings.base.prepopulate = ("default/users",)
     92    ...
     93}}}
     94
     95Function and class definitions can (should) still be at the module level, not inside the config() function.
     96
     97Note that the variable "settings" is passed in as parameter for the config() function - there is no need for {{{settings = current.deployment_settings}}}.
     98
     99The config() function returns nothing.
     100
     101== Adapt all Paths inside the Template ==
     102
     103Some template files may still contain paths with "private/templates" (e.g. views/layout.html). Go through all the files and update these paths so that they find the template at the new location.
     104
     105== Changes in 000_config.py ==
     106
     107In 000_config.py, you can replace this block:
     108{{{
     109path = template_path()
     110if os.path.exists(path):
     111    settings.exec_template(path)
     112}}}
     113
     114with just this:
     115{{{
     116settings.import_template()
     117}}}
     118
     119The old statement will still work, but contains an unnecessary path check which should be avoided. The function template_path() is deprecated and will be removed over time.
     120
     121== Fallbacks ==
     122
     123Most core functions have fallback paths for legacy templates and old-style config.py - but this support will be phased out over time.
     124
     125New core functionality will not support templates at the old location.
     126
     127It is therefore recommended to migrate all templates. Follow the steps above and/or ask for support on our mailing list to migrate your templates.
     128