diff --git a/django/conf/admin_templates/changelist_generic.html b/django/conf/admin_templates/changelist_generic.html deleted file mode 100644 index d8f51c537b..0000000000 --- a/django/conf/admin_templates/changelist_generic.html +++ /dev/null @@ -1,34 +0,0 @@ -{% extends "base_site" %} - -{% block bodyclass %}change-list{% endblock %} - -{% block content %} - -{% if not hide_add_link %} - -{% endif %} - -
-
- - {% if toplinks %} - -
- {% endif %} - - {% if changelist %} - - {% endif %} - -
-
- -{% endblock %} diff --git a/django/conf/global_settings.py b/django/conf/global_settings.py index 41fe147374..52acb51de4 100644 --- a/django/conf/global_settings.py +++ b/django/conf/global_settings.py @@ -65,6 +65,7 @@ TEMPLATE_FILE_EXTENSION = '.html' # See the comments in django/core/template/loader.py for interface # documentation. TEMPLATE_LOADERS = ( +# 'django.core.template.loaders.app_directories.load_template_source', 'django.core.template.loaders.filesystem.load_template_source', # 'django.core.template.loaders.eggs.load_template_source', ) @@ -109,7 +110,7 @@ ALLOWED_INCLUDE_ROOTS = () # If this is a admin settings module, this should be a list of # settings modules (in the format 'foo.bar.baz') for which this admin # is an admin. -ADMIN_FOR = [] +ADMIN_FOR = () # Whether to check the flat-pages table as a last resort for all 404 errors. USE_FLAT_PAGES = True diff --git a/django/conf/project_template/settings/main.py b/django/conf/project_template/settings/main.py index cbb32b7920..1bde7df10a 100644 --- a/django/conf/project_template/settings/main.py +++ b/django/conf/project_template/settings/main.py @@ -30,6 +30,13 @@ MEDIA_URL = '' # Make this unique, and don't share it with anybody. SECRET_KEY = '' +# List of callables that know how to import templates from various sources. +TEMPLATE_LOADERS = ( +# 'django.core.template.loaders.app_directories.load_template_source', + 'django.core.template.loaders.filesystem.load_template_source', +# 'django.core.template.loaders.eggs.load_template_source', +) + MIDDLEWARE_CLASSES = ( "django.middleware.common.CommonMiddleware", "django.middleware.doc.XViewMiddleware", diff --git a/django/core/template/loaders/app_directories.py b/django/core/template/loaders/app_directories.py new file mode 100644 index 0000000000..7319f27fe1 --- /dev/null +++ b/django/core/template/loaders/app_directories.py @@ -0,0 +1,28 @@ +# Wrapper for loading templates from "template" directories in installed app packages. + +from django.conf.settings import INSTALLED_APPS, TEMPLATE_FILE_EXTENSION +from django.core.template import TemplateDoesNotExist +import os + +# At compile time, cache the directories to search. +app_template_dirs = [] +for app in INSTALLED_APPS: + i = app.rfind('.') + m, a = app[:i], app[i+1:] + mod = getattr(__import__(m, '', '', [a]), a) + template_dir = os.path.join(os.path.dirname(mod.__file__), 'templates') + if os.path.isdir(template_dir): + app_template_dirs.append(template_dir) + +# It won't change, so convert it to a tuple to save memory. +app_template_dirs = tuple(app_template_dirs) + +def load_template_source(template_name, template_dirs=None): + for template_dir in app_template_dirs: + filepath = os.path.join(template_dir, template_name) + TEMPLATE_FILE_EXTENSION + try: + return (open(filepath).read(), filepath) + except IOError: + pass + raise TemplateDoesNotExist, template_name +load_template_source.is_usable = True diff --git a/django/core/template/loaders/eggs.py b/django/core/template/loaders/eggs.py index 012e768af2..d01cfc6412 100644 --- a/django/core/template/loaders/eggs.py +++ b/django/core/template/loaders/eggs.py @@ -8,18 +8,18 @@ except ImportError: from django.core.template import TemplateDoesNotExist from django.conf.settings import INSTALLED_APPS, TEMPLATE_FILE_EXTENSION -def load_template_source(name, dirs=None): +def load_template_source(template_name, template_dirs=None): """ Loads templates from Python eggs via pkg_resource.resource_string. - For every installed app, it tries to get the resource (app, name). + For every installed app, it tries to get the resource (app, template_name). """ if resource_string is not None: - pkg_name = 'templates/' + name + TEMPLATE_FILE_EXTENSION + pkg_name = 'templates/' + template_name + TEMPLATE_FILE_EXTENSION for app in INSTALLED_APPS: try: return (resource_string(app, pkg_name), 'egg:%s:%s ' % (app, pkg_name)) except: pass - raise TemplateDoesNotExist, name + raise TemplateDoesNotExist, template_name load_template_source.is_usable = resource_string is not None diff --git a/django/core/template/loaders/filesystem.py b/django/core/template/loaders/filesystem.py index f886cc159a..9a93481705 100644 --- a/django/core/template/loaders/filesystem.py +++ b/django/core/template/loaders/filesystem.py @@ -17,6 +17,6 @@ def load_template_source(template_name, template_dirs=None): if template_dirs: error_msg = "Tried %s" % tried else: - error_msg = "Your TEMPLATE_DIRS settings is empty. Change it to point to at least one template directory." + error_msg = "Your TEMPLATE_DIRS setting is empty. Change it to point to at least one template directory." raise TemplateDoesNotExist, error_msg load_template_source.is_usable = True diff --git a/django/views/defaults.py b/django/views/defaults.py index d283e54c1b..decc220cf7 100644 --- a/django/views/defaults.py +++ b/django/views/defaults.py @@ -10,8 +10,12 @@ def shortcut(request, content_type_id, object_id): obj = content_type.get_object_for_this_type(pk=object_id) except ObjectDoesNotExist: raise Http404, "Content type %s object %s doesn't exist" % (content_type_id, object_id) - if not hasattr(obj, 'get_absolute_url'): + try: + absurl = obj.get_absolute_url() + except AttributeError: raise Http404, "%s objects don't have get_absolute_url() methods" % content_type.name + if absurl.startswith('http://'): + return httpwrappers.HttpResponseRedirect(absurl) object_domain = None if hasattr(obj, 'get_site_list'): site_list = obj.get_site_list() @@ -27,8 +31,8 @@ def shortcut(request, content_type_id, object_id): except sites.SiteDoesNotExist: pass if not object_domain: - return httpwrappers.HttpResponseRedirect(obj.get_absolute_url()) - return httpwrappers.HttpResponseRedirect('http://%s%s' % (object_domain, obj.get_absolute_url())) + return httpwrappers.HttpResponseRedirect(absurl) + return httpwrappers.HttpResponseRedirect('http://%s%s' % (object_domain, absurl)) def page_not_found(request): """ diff --git a/docs/design_philosophies.txt b/docs/design_philosophies.txt index 2084c992a5..2988672f02 100644 --- a/docs/design_philosophies.txt +++ b/docs/design_philosophies.txt @@ -242,3 +242,9 @@ Loose coupling A view shouldn't care about which template system the developer uses -- or even whether a template system is used at all. + +Designate between GET and POST +------------------------------ + +GET and POST are distinct; developers should explicitly use one or the other. +The framework should make it easy to distinguish between GET and POST data. diff --git a/docs/django-admin.txt b/docs/django-admin.txt index ba9bb1403f..0faabbfcca 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -112,6 +112,11 @@ them to standard output, but it won't stop the server. You can run as many servers as you want, as long as they're on separate ports. Just execute ``django-admin.py runserver`` more than once. +Note that the default IP address, 127.0.0.1, is not accessible from other +machines on your network. To make your development server viewable to other +machines on the network, use its own IP address (e.g. ``192.168.2.1``) or +``0.0.0.0``. + Examples: ~~~~~~~~~ diff --git a/docs/model-api.txt b/docs/model-api.txt index 140518e80e..ee5f9ee723 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -252,7 +252,7 @@ Here are all available field types: Using a `FieldField` or an ``ImageField`` (see below) in a model takes a few steps: - 1. In your settings file, you'll need to define ``MEDIA_ROOT``as the + 1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the full path to a directory where you'd like Django to store uploaded files. (For performance, these files are not stored in the database.) Define ``MEDIA_URL`` as the base public URL of that directory. Make diff --git a/docs/settings.txt b/docs/settings.txt new file mode 100644 index 0000000000..382a661be9 --- /dev/null +++ b/docs/settings.txt @@ -0,0 +1,521 @@ +=============== +Django settings +=============== + +A Django settings file contains all the configuration of your Django +installation. This document explains how settings work and which settings are +available. + +The basics +========== + +A settings file is just a Python module with module-level variables. + +Here are a couple of example settings:: + + DEBUG = False + DEFAULT_FROM_EMAIL = 'webmaster@example.com' + TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john') + +Because a settings file is a Python module, the following apply: + + * It shouldn't have Python syntax errors. + * It can assign settings dynamically using normal Python syntax. + For example:: + + MY_SETTING = [str(i) for i in range(30)] + + * It can import values from other settings files. + +Designating the settings +======================== + +When you use Django, you have to tell it which settings you're using. Do this +by using an environment variable, ``DJANGO_SETTINGS_MODULE``. + +The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g. +``"myproject.settings.main"``. Note that the settings module should be on the +Python `import search path`_. + +.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html + +The django-admin.py utility +--------------------------- + +When using `django-admin.py`_, you can either set the environment variable +once, or explicitly pass in the settings module each time you run the utility. + +Example (Unix Bash shell):: + + export DJANGO_SETTINGS_MODULE=myproject.settings.main + django-admin.py runserver + +Example (Windows shell):: + + set DJANGO_SETTINGS_MODULE=myproject.settings.main + django-admin.py runserver + +Use the ``--settings`` command-line argument to specify the settings manually:: + + django-admin.py runserver --settings=myproject.settings.main + +.. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/ + +On the server (mod_python) +-------------------------- + +In your live server environment, you'll need to tell Apache/mod_python which +settings file to use. Do that with ``SetEnv``:: + + + SetHandler python-program + PythonHandler django.core.handlers.modpython + SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main + + +Read the `Django mod_python documentation`_ for more information. + +.. _Django mod_python documentation: http://www.djangoproject.com/documentation/mod_python/ + +Default settings +================ + +A Django settings file doesn't have to define any settings if it doesn't need +to. Each setting has a sensible default value. These defaults live in the file +``django/conf/global_settings.py``. + +Here's the algorithm Django uses in compiling settings: + + * Load settings from ``global_settings.py``. + * Load settings from the specified settings file, overriding the global + settings as necessary. + +Note that a settings file should *not* import from ``global_settings``, because +that's redundant. + +Using settings in Python code +============================= + +In your Django apps, use settings by importing them from +``django.conf.settings``. Example:: + + from django.conf.settings import DEBUG + + if DEBUG: + # Do something + +Note that your code should *not* import from either ``global_settings`` or +your own settings file. ``django.conf.settings`` abstracts the concepts of +default settings and site-specific settings; it presents a single interface. + +Altering settings at runtime +============================ + +You shouldn't alter settings in your applications at runtime. For example, +don't do this in a view:: + + from django.conf.settings import DEBUG + + DEBUG = True # Don't do this! + +The only place you should assign to settings is in a settings file. + +Security +======== + +Because a settings file contains sensitive information, such as the database +password, you should make every attempt to limit access to it. For example, +change its file permissions so that only you and your Web server's user can +read it. This is especially important in a shared-hosting environment. + +Available settings +================== + +Here's a full list of all available settings, in alphabetical order, and their +default values. + +ABSOLUTE_URL_OVERRIDES +---------------------- + +Default: ``{}`` (Empty dictionary) + +A dictionary mapping ``"app_label.module_name"`` strings to functions that take +a model object and return its URL. This is a way of overriding +``get_absolute_url()`` methods on a per-installation basis. Example:: + + ABSOLUTE_URL_OVERRIDES = { + 'blogs.blogs': lambda o: "/blogs/%s/" % o.slug, + 'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug), + } + +ADMIN_FOR +--------- + +Default: ``()`` (Empty list) + +Used for admin-site settings modules, this should be a tuple of settings +modules (in the format ``'foo.bar.baz'``) for which this site is an admin. + +ADMIN_MEDIA_PREFIX +------------------ + +Default: ``'/media/'`` + +The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use +a trailing slash. + +ADMINS +------ + +Default: ``()`` (Empty tuple) + +A tuple that lists people who get code error notifications. When +``DEBUG=False`` and a view raises an exception, Django will e-mail these people +with the full exception information. Each member of the tuple should be a tuple +of (Full name, e-mail address). Example:: + + (('John', 'john@example.com'), ('Mary', 'mary@example.com')) + +ALLOWED_INCLUDE_ROOTS +--------------------- + +Default: ``()`` (Empty tuple) + +A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template +tag. This is a security measure, so that template authors can't access files +that they shouldn't be accessing. + +For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``, +then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}`` +wouldn't. + +APPEND_SLASH +------------ + +Default: ``True`` + +Whether to append trailing slashes to URLs. This is only used if +``CommonMiddleware`` is installed (see the `middleware docs`_). See also +``PREPEND_WWW``. + +CACHE_BACKEND +------------- + +Default: ``'simple://'`` + +The cache backend to use. See the `cache docs`_. + +CACHE_MIDDLEWARE_KEY_PREFIX + +Default: ``''`` (Empty string) + +The cache key prefix that the cache middleware should use. See the +`cache docs`_. + +DATABASE_ENGINE +--------------- + +Default: ``'postgresql'`` + +Which database backend to use. Either ``'postgresql'``, ``'mysql'``, +``'sqlite3'`` or ``'ado_mssql'``. + +DATABASE_HOST +------------- + +Default: ``''`` (Empty string) + +Which host to use when connecting to the database. An empty string means +localhost. Not used with SQLite. + +DATABASE_NAME +------------- + +Default: ``''`` (Empty string) + +The name of the database to use. For SQLite, it's the full path to the database +file. + +DATABASE_PASSWORD +----------------- + +Default: ``''`` (Empty string) + +The password to use when connecting to the database. Not used with SQLite. + +DATABASE_PORT +------------- + +Default: ``''`` (Empty string) + +The port to use when connecting to the database. An empty string means the +default port. Not used with SQLite. + +DATABASE_USER +------------- + +Default: ``''`` (Empty string) + +The username to use when connecting to the database. Not used with SQLite. + +DEBUG +----- + +Default: ``False`` + +A boolean that turns on/off debug mode. + +DEFAULT_CHARSET +--------------- + +Default: ``'utf-8'`` + +Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't +manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the +``Content-Type`` header. + +DEFAULT_CONTENT_TYPE +-------------------- + +Default: ``'text/html'`` + +Default content type to use for all ``HttpResponse`` objects, if a MIME type +isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the +``Content-Type`` header. + +DEFAULT_FROM_EMAIL +------------------ + +Default: ``'webmaster@localhost'`` + +Default e-mail address to use for various automated correspondence from the +site manager(s). + +DISALLOWED_USER_AGENTS +---------------------- + +Default: ``()`` (Empty tuple) + +List of compiled regular expression objects representing User-Agent strings +that are not allowed to visit any page, systemwide. Use this for bad +robots/crawlers. This is only used if ``CommonMiddleware`` is installed (see +the `middleware docs`_). + +EMAIL_HOST +---------- + +Default: ``'localhost'`` + +The host to use for sending e-mail. + +EMAIL_SUBJECT_PREFIX +-------------------- + +Default: ``'[Django] '`` + +Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins`` +or ``django.core.mail.mail_managers``. You'll probably want to include the +trailing space. + +IGNORABLE_404_ENDS +------------------ + +Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')`` + +See also ``IGNORABLE_404_STARTS``. + +IGNORABLE_404_STARTS +-------------------- + +Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')`` + +A tuple of strings that specify beginnings of URLs that should be ignored by +the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS`` and ``IGNORABLE_404_ENDS``. + +INTERNAL_IPS +------------ + +Default: ``()`` (Empty tuple) + +A tuple of IP addresses, as strings, that: + + * See debug comments, when ``DEBUG`` is ``True`` + * Receive X headers if the ``XViewMiddleware`` is installed (see the + `middleware docs`_) + +JING_PATH +--------- + +Default: ``'/usr/bin/jing'`` + +Path to the "Jing" executable. Jing is a RELAX NG validator, and Django uses it +to validate each ``XMLField`` in your models. +See http://www.thaiopensource.com/relaxng/jing.html . + +LANGUAGE_CODE +------------- + +Default: ``'en-us'`` + +A string representing the language code for this installation. + +MANAGERS +-------- + +Default: ``ADMINS`` (Whatever ``ADMINS`` is set to) + +A tuple in the same format as ``ADMINS`` that specifies who should get +broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``. + +MEDIA_ROOT +---------- + +Default: ``''`` (Empty string) + +Absolute path to the directory that holds media for this installation. +Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``. + +MEDIA_URL +--------- + +Default: ``''`` (Empty string) + +URL that handles the media served from ``MEDIA_ROOT``. +Example: ``"http://media.lawrence.com"`` + +MIDDLEWARE_CLASSES +------------------ + +Default: ``("django.middleware.sessions.SessionMiddleware", "django.middleware.common.CommonMiddleware", "django.middleware.doc.XViewMiddleware")`` + +A tuple of middleware classes to use. See the `middleware docs`_. + +PREPEND_WWW +----------- + +Default: ``False`` + +Whether to prepend the "www." subdomain to URLs that don't have it. This is +only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). +See also ``APPEND_SLASH``. + +SECRET_KEY +---------- + +Default: ``''`` (Empty string) + +A secret key for this particular Django installation. Used to provide a seed in +secret-key hashing algorithms. Set this to a random string -- the longer, the +better. ``django-admin.py startproject`` creates one automatically. + +SEND_BROKEN_LINK_EMAILS +----------------------- + +Default: ``False`` + +Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a +Django-powered page that is 404ed with a non-empty referer (i.e., a broken +link). This is only used if ``CommonMiddleware`` is installed (see the +`middleware docs`_). See also ``IGNORABLE_404_STARTS`` and +``IGNORABLE_404_ENDS``. + +SERVER_EMAIL +------------ + +Default: ``'root@localhost'`` + +The e-mail address that error messages come from, such as those sent to +``ADMINS`` and ``MANAGERS``. + +SESSION_COOKIE_AGE +------------------ + +Default: ``1209600`` (2 weeks, in seconds) + +The age of session cookies, in seconds. See the `session docs`_. + +SESSION_COOKIE_DOMAIN +--------------------- + +Default: ``None`` + +The domain to use for session cookies. Set this to a string such as +``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard +domain cookie. See the `session docs`_. + +SESSION_COOKIE_NAME +------------------- + +Default: ``'hotclub'`` + +The name of the cookie to use for sessions. This can be whatever you want. +See the `session docs`_. + +``'hotclub'`` is a reference to the Hot Club of France, the band Django +Reinhardt played in. + +TEMPLATE_DIRS +------------- + +Default: ``()`` (Empty tuple) + +List of locations of the template source files, in search order. See the +`template documentation`_. + +TEMPLATE_FILE_EXTENSION +----------------------- + +Default: ``'.html'`` + +The file extension to append to all template names when searching for +templates. See the `template documentation`_. + +TEMPLATE_LOADERS +---------------- + +Default: ``('django.core.template.loaders.filesystem.load_template_source',)`` + +A tuple of callables (as strings) that know how to import templates from +various sources. See the `template documentation`_. + +TIME_ZONE +--------- + +Default: ``'America/Chicago'`` + +A string representing the time zone for this installation. +`See available choices`_. + +USE_ETAGS +--------- + +Default: ``False`` + +A boolean that specifies whether to output the "Etag" header. This saves +bandwidth but slows down performance. This is only used if ``CommonMiddleware`` +is installed (see the `middleware docs`_). + +USE_FLAT_PAGES +-------------- + +Default: ``True`` + +Whether to check the flat-pages table as a last resort for all 404 errors. This +is only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). + +.. _cache docs: http://www.djangoproject.com/documentation/cache/ +.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ +.. _session docs: http://www.djangoproject.com/documentation/sessions/ +.. _See available choices: http://www.postgresql.org/docs/current/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE +.. _template documentation: http://www.djangoproject.com/documentation/templates_python/ + +Creating your own settings +========================== + +There's nothing stopping you from creating your own settings, for your own +Django apps. Just follow these conventions: + + * Setting names are in all uppercase. + * For settings that are sequences, use tuples instead of lists. This is + purely for performance. + * Don't reinvent an already-existing setting. diff --git a/docs/templates.txt b/docs/templates.txt index 843ed0cbaa..5c52371c8a 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -224,6 +224,13 @@ Here are some tips for working with inheritance: if you want to add to the contents of a parent block instead of completely overriding it. +Finally, note that you can't define multiple ``{% block %}`` tags with the same +name in the same template. This limitation exists because a block tag works in +"both" directions. That is, a block tag doesn't just provide a hole to fill -- +it also defines the content that fills the hole in the *parent*. If there were +two similarly-named ``{% block %}`` tags in a template, that template's parent +wouldn't know which one of the blocks' content to use. + Using the built-in reference ============================ @@ -392,13 +399,13 @@ Built-in tag reference block are output:: {% if athlete_list %} - Number of athletes: {{ athlete_list|count }} + Number of athletes: {{ athlete_list|length }} {% else %} No athletes. {% endif %} In the above, if ``athlete_list`` is not empty, the number of athletes will be - displayed by the ``{{ athlete_list|count }}`` variable. + displayed by the ``{{ athlete_list|length }}`` variable. As you can see, the ``if`` tag can take an option ``{% else %}`` clause that will be displayed if the test fails. @@ -425,8 +432,8 @@ Built-in tag reference {% if athlete_list %} {% if coach_list %} - Number of athletes: {{ athlete_list|count }}. - Number of coaches: {{ coach_list|count }}. + Number of athletes: {{ athlete_list|length }}. + Number of coaches: {{ coach_list|length }}. {% endif %} {% endif %} diff --git a/docs/templates_python.txt b/docs/templates_python.txt index bd8aea62c7..b4e09252bd 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -287,8 +287,12 @@ Generally, you'll store templates in files on your filesystem rather than using the low-level ``Template`` API yourself. Save templates in a file with an ".html" extension in a directory specified as a **template directory**. -(The ".html" extension is just a required convention. It doesn't mean templates -can only contain HTML. They can contain whatever textual content you want.) +If you don't like the requirement that templates have an ".html" extension, +change your ``TEMPLATE_FILE_EXTENSION`` setting. It's set to ``".html"`` by +default. + +Also, the .html extension doesn't mean templates can contain only HTML. They +can contain whatever textual content you want. The TEMPLATE_DIRS setting ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -355,6 +359,47 @@ To load a template that's within a subdirectory, just use a slash, like so:: get_template("news/story_detail") +Loader types +~~~~~~~~~~~~ + +By default, Django uses a filesystem-based template loader, but Django comes +with a few other template loaders. They're disabled by default, but you can +activate them by editing your ``TEMPLATE_LOADERS`` setting. +``TEMPLATE_LOADERS`` should be a tuple of strings, where each string represents +a template loader. Here are the built-in template loaders: + +``django.core.template.loaders.filesystem.load_template_source`` + Loads templates from the filesystem, according to ``TEMPLATE_DIRS``. + +``django.core.template.loaders.app_directories.load_template_source`` + Loads templates from Django apps on the filesystem. For each app in + ``INSTALLED_APPS``, the loader looks for a ``templates`` subdirectory. If + the directory exists, Django looks for templates in there. + + This means you can store templates with your individual apps. This also + makes it easy to distribute Django apps with default templates. + + For example, for this setting:: + + INSTALLED_APPS = ('myproject.polls', 'myproject.music') + + ...then ``get_template("foo")`` will look for templates in these + directories, in this order: + + * ``/path/to/myproject/polls/templates/foo.html`` + * ``/path/to/myproject/music/templates/music.html`` + + Note that the loader performs an optimization when it is first imported: + It caches a list of which ``INSTALLED_APPS`` packages have a ``templates`` + subdirectory. + +``django.core.template.loaders.eggs.load_template_source`` + Just like ``app_directories`` above, but it loads templates from Python + eggs rather than from the filesystem. + +Django uses the template loaders in order according to the ``TEMPLATE_LOADERS`` +setting. It uses each loader until a loader finds a match. + Extending the template system =============================