mirror of
https://github.com/jazzband/django-dbtemplates.git
synced 2026-03-16 22:20:28 +00:00
239 lines
8.4 KiB
Text
239 lines
8.4 KiB
Text
===================================
|
|
Database template loader for Django
|
|
===================================
|
|
|
|
``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.
|
|
|
|
.. _template loader: http://docs.djangoproject.com/en/dev/ref/templates/api/#loading-templates
|
|
|
|
.. contents:: Table of Contents
|
|
:backlinks: none
|
|
|
|
Setup
|
|
=====
|
|
|
|
1. 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``.
|
|
2. Follow the instructions in the INSTALL file
|
|
3. 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',
|
|
)
|
|
|
|
4. Sync your database ``python manage.py syncdb``
|
|
5. Restart your Django server
|
|
|
|
.. _Mercurial repository: http://bitbucket.org/jezdez/django-dbtemplates/
|
|
|
|
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:
|
|
|
|
1. Open your command line and change to the ``example`` directory in the
|
|
directory with the extracted source distribution.
|
|
2. Run ``python manage.py syncdb`` and follow the instructions.
|
|
3. Run ``python manage.py runserver`` and open your favorite browser with the
|
|
address http://127.0.0.1:8000/admin/.
|
|
4. 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>
|
|
|
|
5. 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.
|
|
6. 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``.
|
|
|
|
.. _flatpages app: http://docs.djangoproject.com/en/dev/ref/contrib/flatpages/
|
|
|
|
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.
|
|
|
|
.. _cache documentation: http://docs.djangoproject.com/en/dev/topics/cache/#setting-up-the-cache
|
|
|
|
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.
|
|
|
|
.. _source of the default backends: http://bitbucket.org/jezdez/django-dbtemplates/src/tip/dbtemplates/cache.py
|
|
|
|
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`` automatically recognizes if
|
|
``django-reversion`` is installed and works out of the box. Just visit the
|
|
"History" section of each template instance and browse its history.
|
|
|
|
Short installation howto
|
|
------------------------
|
|
|
|
1. Get the source from the `django-reversion`_ project site and put it
|
|
somewhere on your `PYTHONPATH`.
|
|
2. Add ``reversion`` to the ``INSTALLED_APPS`` setting of your Django project
|
|
3. Sync your database with ``python manage.py syncdb``
|
|
|
|
.. _django-reversion: http://code.google.com/p/django-reversion/
|
|
.. _django-reversion's documentation: http://code.google.com/p/django-reversion/wiki/GettingStarted
|
|
|
|
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.
|
|
|
|
.. _Django management commands: http://docs.djangoproject.com/en/dev/ref/django-admin/
|
|
|
|
Support
|
|
=======
|
|
|
|
Please leave your questions and messages on the designated site:
|
|
|
|
http://bitbucket.org/jezdez/django-dbtemplates/issues/
|