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

Timestamp:

01/05/15 08:56:21 (11 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelines/Templates/Migration

@@ +1 @@
+= Migration of Templates to modules/templates =
+[[TOC]]
+
+== Introduction ==
+
+We have changed the way templates are handled:
+
+  * templates now live in modules/templates (formerly private/templates)
+  * the template's config.py is now a Python module instead of a Python script and will be imported rather than executed
+  * the settings in config.py have been moved into a function config()
+
+This has a couple of advantages:
+
+  * being in the modules-path, templates can be imported and do not need to be re-compiled and executed on every request
+  * templates are treated as Python packages so that config.py can import template-specific modules
+  * config.py can now define classes and functions without risk for memory leaks
+  * templates can share common modules via regular imports
+
+We 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.
+
+== Moving to modules/templates ==
+
+Copy the entire template folder to modules/templates.
+
+== Refactoring config.py ==
+
+Re-structure config.py so that all settings-assignment are inside a function config():
+
+Old config.py:
+{{{
+# -*- coding: utf-8 -*-
+
+try:
+    # Python 2.7
+    from collections import OrderedDict
+except:
+    # Python 2.6
+    from gluon.contrib.simplejson.ordered_dict import OrderedDict
+
+from gluon import current
+from gluon.storage import Storage
+
+T = current.T
+settings = current.deployment_settings
+
+"""
+    Template settings
+
+    All settings which are to configure a specific template are located here
+
+    Deployers should ideally not need to edit any other files outside of their template folder
+"""
+
+settings.base.system_name = "Example"
+settings.base.system_name_short = "Example"
+
+# PrePopulate data
+settings.base.prepopulate = ("default/users",)
+...
+}}}
+
+New config.py:
+{{{
+# -*- coding: utf-8 -*-
+
+try:
+    # Python 2.7
+    from collections import OrderedDict
+except:
+    # Python 2.6
+    from gluon.contrib.simplejson.ordered_dict import OrderedDict
+
+from gluon import current
+from gluon.storage import Storage
+
+def config(settings):
+    """
+        Template settings
+
+        All settings which are to configure a specific template are located here
+
+        Deployers should ideally not need to edit any other files outside of their template folder
+    """
+
+    T = current.T
+
+    settings.base.system_name = "Example"
+    settings.base.system_name_short = "Example"
+
+    # PrePopulate data
+    settings.base.prepopulate = ("default/users",)
+    ...
+}}}
+
+Function and class definitions can (should) still be at the module level, not inside the config() function.
+
+Note that the variable "settings" is passed in as parameter for the config() function - there is no need for {{{settings = current.deployment_settings}}}.
+
+The config() function returns nothing.
+
+== Adapt all Paths inside the Template ==
+
+Some 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.
+
+== Changes in 000_config.py ==
+
+In 000_config.py, you can replace this block:
+{{{
+path = template_path()
+if os.path.exists(path):
+    settings.exec_template(path)
+}}}
+
+with just this:
+{{{
+settings.import_template()
+}}}
+
+The 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.
+
+== Fallbacks ==
+
+Most core functions have fallback paths for legacy templates and old-style config.py - but this support will be phased out over time.
+
+New core functionality will not support templates at the old location.
+
+It is therefore recommended to migrate all templates. Follow the steps above and/or ask for support on our mailing list to migrate your templates.
+