Template loader for database stored templates with extensible cache backend
Project description
dbtemplates is a Django app that comes with to parts: It allows you to create templates that are saved in your database, and it provides a so called template loader, a function that enables Django to find the templates you created in the database.
It also includes a extensible caching mechanism and supports version control of the templates saved in the database.
Setup
Get the source from the Mercurial repository or install it from the Python Package Index by running easy_install django-dbtemplates or pip django-dbtemplates.
Follow the instructions in the INSTALL file
Edit the settings.py of your Django site:
Add dbtemplates to the INSTALLED_APPS setting
Check if django.contrib.sites and django.contrib.admin are in INSTALLED_APPS and add if necessary.
It should look something like this:
INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.admin', 'django.contrib.flatpages', # .. 'dbtemplates', )Add dbtemplates.loader.load_template_source to the TEMPLATE_LOADERS list in the settings.py of your Django project
It should look something like this:
TEMPLATE_LOADERS = ( 'django.template.loaders.filesystem.load_template_source', 'django.template.loaders.app_directories.load_template_source', 'dbtemplates.loader.load_template_source', )
Sync your database python manage.py syncdb
Restart your Django server
Usage
Creating database templates is pretty simple: Just open the admin interface of your Django-based site in your browser and click on “Templates” in the “Dbtemplates” section.
There you only need to fill in the name field with the identifier, Django is supposed to use while searching for templates, e.g. blog/entry_list.html. The content field should be filled with the content of your template.
Optionally, by leaving the content field empty you are able to tell dbtemplates to look for a template with the name by using Django’s other template loaders. For example, if you have a template called blog/entry_list.html on your file system and want to save the templates contents in the database, you just need to leave the content field empty to automatically populate it. That’s especially useful if you don’t want to copy and paste its content manually to the textarea.
Example
dbtemplates comes with an example Django project that let’s you try it out. The example uses Django’s own flatpages app to enable you to create a simple page using dbtemplates. Flat pages are a perfect fit to dbtemplates since they come prepackaged and are simple to use.
Here is how it works:
Open your command line and change to the example directory in the directory with the extracted source distribution.
Run python manage.py syncdb and follow the instructions.
Run python manage.py runserver and open your favorite browser with the address http://127.0.0.1:8000/admin/.
Next add a new Template object in the dbtemplates section and use flatpages/default.html as the value for the name field. For the content field use this example:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <html> <head> <title>{{ flatpage.title }}</title> </head> <body> {{ flatpage.content }} </body> </html>Return to the home screen of the admin interface and add a new flat page. Use / (yep, just a forward slash) and whatever title and content you prefer. Please make sure you select the default site example.com before you save the flat page.
Visit http://127.0.0.1:8000/ and see the flat page you just created rendered with the flatpages/default.html template provided by dbtemplates.
Settings
DBTEMPLATES_ADD_DEFAULT_SITE
dbtemplates adds the current site (settings.SITE_ID) to the database template when it is created by default. You can disable this feature by setting DBTEMPLATES_ADD_DEFAULT_SITE to False.
DBTEMPLATES_AUTO_POPULATE_CONTENT
dbtemplates auto-populates the content of a newly created template with the content of a template with the same name the other template loader. To disable this feature set DBTEMPLATES_AUTO_POPULATE_CONTENT to False.
DBTEMPLATES_CACHE_BACKEND
The dotted Python path to the cache backend class. See Caching for details.
DBTEMPLATES_CACHE_DIR
A directory path that is used by the cache FileSystemBackend to store the cached templates. See Caching for details.
DBTEMPLATES_USE_CODEMIRROR
A boolean, if enabled triggers the use of the CodeMirror based editor. Set to False by default.
DBTEMPLATES_USE_REVERSION
A boolean, if enabled triggers the use of django-reversion.
DBTEMPLATES_MEDIA_PREFIX
The URL prefix for dbtemplates’ media – CSS and JavaScript used by the CodeMirror based editor. Make sure to use a trailing slash, and to have this be different from the MEDIA_URL setting (since the same URL cannot be mapped onto two different sets of files).
Caching
Using the default caching
Dbtemplates comes with different backends for caching that are automatically created, updated and deleted when templates are saved in the database by using Django’s signal framework.
To enable one of them you need to specify a setting called DBTEMPLATES_CACHE_BACKEND to one of the following values:
dbtemplates.cache.FileSystemBackend – File system caching
The FileSystemBackend is a simple way to store the templates you have in the database on the filesystem. That’s especially useful if you don’t use a full caching framework like Django is providing.
To use this backend you need additionally create a setting DBTEMPLATES_CACHE_DIR that contains the full file system path to the directory where dbtemplates should create the cache files in.
dbtemplates.cache.DjangoCacheBackend – Django cache
The DjangoCacheBackend is a thin wrapper around Django’s caching framework that enables you to use advanced caching solutions like memcached or database caching. Please see the cache documentation if you want to know more about it.
Writing your own caching backends
Writing your own cache backends is perfectly easy since dbtemplates includes a easy-to-use base class in dbtemplates.cache.BaseCacheBackend.
Just subclass that base backend somewhere in your own code and provide the follwing three reuqired methods:
load
Loads a template from the cache with the given name and returns its contents. Return None if nothing found.
Arguments:
name - name of the template
save
Saves the passed template contents with the passed name in the cache.
Arguments:
name - name of the template
content - contents of the template
remove
Removes the template with the passed name from the cache.
Arguments:
name - name of the template
Please see also the source of the default backends to see how it works.
Versionizing your templates
dbtemplates comes prepared to use the third party Django app django-reversion, that once installed besides dbtemplates allows you to jump back to old versions of your templates. It automatically saves every state when you save the template in your database and provides an easy to use interface.
Please refer to django-reversion’s documentation for more information about how it works. dbtemplates uses django-reversion if the DBTEMPLATES_USE_REVERSION setting is True. Just visit the “History” section of each template instance and browse its history.
Short installation howto
Get the source from the django-reversion project site and put it somewhere on your PYTHONPATH.
Add reversion to the INSTALLED_APPS setting of your Django project
Sync your database with python manage.py syncdb
Management commands
dbtemplates comes with two Django management commands to be used with django-admin.py or manage.py:
sync_templates
Enables you to sync your already existing file systems templates with the database. It will guide you through the whole process.
create_error_templates
Tries to add the two templates 404.html and 500.html that are used by Django when a error occurs.
Admin actions
dbtemplates provides two admin actions to be used with Django>=1.1.
invalidate_cache
Invalidates the cache of the selected templates by calling the appropriate cache backend methods.
repopulate_cache
Repopulates the cache with selected templates by invalidating it first and filling then after that.
Changelog
0.7.4 (09-23-10)
Fixed tests.
0.7.3 (09-21-10)
Added DBTEMPLATES_AUTO_POPULATE_CONTENT setting to be able to disable to auto-populating of template content.
Fixed cosmetic issue in admin with collapsable fields.
0.7.2 (09-04-10)
Moved to Github again. Sigh.
0.7.1 (07-07-10)
Fixed problem with the CodeMirror textarea, which wasn’t completely disabled before.
Fixed problem with the DBTEMPLATES_MEDIA_PREFIX setting, which defaults now to os.path.join(settings.MEDIA_ROOT, 'dbtemplates') now.
In other words, if you don’t specify a DBTEMPLATES_MEDIA_PREFIX setting and have the CodeMirror textarea enabled, dbtemplates will look in a subdirectory of your site’s MEDIA_ROOT for the CodeMirror media files.
0.7.0 (06-24-10)
Added CodeMirror-based syntax highlighting textarea, based on the amaxing work by Nic Pottier. Set the DBTEMPLATES_USE_CODEMIRROR setting to True to enable it.
Make use of the full width in plain textarea mode.
Added Chinese translation
Added support for Django 1.2
Updated French translation
Added DBTEMPLATES_USE_REVERSION setting to be able to explicitely enable reversion support. (Default: False)
0.6.1 (10-19-09):
Fixed issue with default site of a template, added ability to disable default site (DBTEMPLATES_ADD_DEFAULT_SITE).
0.6.0 (10-09-09):
Updated and added locales (Danish, Brazilian Portuguese)
Fixes an ambiguity problem with the cache invalidation
Added invalidate_cache and repopulate_cache admin actions
Added Sphinx documentation
0.5.7
Updates to the docs
switch back to Bitbucket
fixed tests
Added Italian translation
list of sites the template is used on
fixed bug in create_error_template command.
0.5.4
Made loader and cache backends site-aware.
The filesystem cache backend now saves the files under <dir>/<site_domain>/<file_name>.
The Django cache backend the Site id in the cache key
Template is now saved explicitly to backend if not existent in cache (e.g. if deleted manually or invalidated).
0.5.3
Removed automatic creation of 404.html and 500.html templates and added a new management command for those cases called create_error_templates
Also reverted move to Bitbucket
0.5.2
Fixed a problem with django.contrib.sites when its table hasn’t been populated yet on initialization of dbtemplates. Thanks for the report, Kevin Fricovsky
Added an example Django project and docs for it
0.5.1
Removed unneeded code that registered the model with reversion.
Updated docs a bit.
Moved codebase to Bitbucket.
Removed legacy sync_templates.py script, use django-admin.py sync_templates from now on.
0.5.0
Added support for django-reversion
added feature that populates the content field automatically when left empty by using Django’s other template loaders
added caching backend system with two default backends:
FileSystemBackend
DjangoCacheBackend
More about it in the blog post and in the docs.
0.4.7
Minor bugfix
0.4.6
Minor doc change and PyPI support
0.4.5
fixed the –force option of the sync_templates command
0.4.4
fixed error in custom model save() after changes in Django r8670.
0.4.3
removed oldforms code
0.4.2
added Hebrew translation (by mkriheli)
0.4.1
added French (by Roland Frederic) and German locale
0.4.0
adds better support for newforms-admin
don’t forget to load the dbtemplates.admin, e.g. by using django.contrib.admin.autodiscover() in you urls.py
0.3.1
adds a new management command sync_templates for bidirectional syncing between filesystem and database (backwards-compatible) and FilesystemCaching (thanks, Arne Brodowski!)
0.2.5
adds support for newforms-admin
Support
Please leave your questions and messages on the designated site:
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
