What does "load" do in Django Templates?

Question

As "load" is far too generic for searching:

1. What is the purpose of "load" and what does it do in this particular case? - in a template file, base_weblog.html,

   {% load weblog %}{% render_month_links %}

2. Are some naming conventions used in order for "load" to do its job? E.g. names of folders and/or files and/or class names?

3. Where is the documentation for "load" and can you elaborate?

---

Details:

The example is from the source for http://www.djangoproject.com/ - direct download URL is through http://shrinkster.com/17g8.

Partial folder structure (items with no file extension are folders):

django_website

  apps
    accounts
    aggregator
    blog
      urls.py
      models.py
        class Entry(models.Model)

      templatetags
        weblog.py
    contact
    docs

  templates
    base_weblog.html

    aggregator
    blog
      entry_archive.html
      entry_archive_year.html
      month_links_snippet.html
      entry_archive_month.html
      entry_detail.html
      entry_snippet.html
      entry_archive_day.html
    comments
    contact
    docs
    feeds
    flatfiles
    flatpages
    registration

Answer 1

load tag can load built-in and custom Django template tags and filters by setting the files in load tag.

For example of a custom Django template tag and filter, create templatetags folder with __init__.py(Empty file) and custom_tags.py in core folder where settings.py is as shown below, then don't forget to restart server to apply custom_tags.py to Django project. *Other names are fine for custom_tags.py and according to my experiments, custom_tags.py works without __init__.py(Empty file) but basically, it is better to create __init__.py(Empty file) just under templatetags folder by following what the doc says:

django-project
 |-core
 |  |-settings.py
 |  └-templatetags # Here
 |     |-__init__.py
 |     └-custom_tags.py
 |-templates
 |  └-index.html
 |-app1
 └-app2

And, don't forget to set core to INSTALLED_APPS in settings.py to apply custom_tags.py to Django project as shown below. *Setting core to INSTALLED_APPS also can collect the static files in core folder to the root Django Project folder with python manage.py collectstatic. I recommend to set core to INSTALLED_APPS before you start building your Django Project:

# "core/settings.py"

INSTALLED_APPS = [
    # ...
    'core', # Here
    'app1',
    'app2',
]

Then, create uppercase and lowercase tags in custom_tags.py as shown below. *You can see my answer explaining @register.simple_tag:

# "core/templatetags/custom_tags.py"

from django.template import Library

register = Library()

@register.simple_tag
def uppercase(arg):
    return arg.upper()

@register.filter
def lowercase(arg):
    return arg.lower()

Then, you need to set the file custom_tags by omitting .py in load tag to use uppercase and lowercase tags as shown below:

# "templates/index.html"

{% load custom_tags %}

{% uppercase "Hello World" %} # HELLO WORLD
{{ "Hello World" | lowercase }} # hello world

And, you can also create the folders like app1 and app2 with __init__.py(Empty file) and custom_tags.py in templatetags folder as shown below. *Other names are fine for app1 and app2 folders and according to my experiments, custom_tags.py in app1 and app2 folders doesn't work without __init__.py(Empty file) so __init__.py(Empty file) must be created just under app1 and app2 folders:

django-project
 |-core
 |  |-settings.py
 |  └-templatetags
 |     |-app1 # Here
 |     |  |-__init__.py
 |     |  └-custom_tags.py
 |     |-app2 # Here
 |     |  |-__init__.py
 |     |  └-custom_tags.py
 |     |-__init__.py
 |     └-custom_tags.py
 |-templates
 |  └-index.html
 |-app1
 └-app2

Then, you need to set the file custom_tags following the folders app1 and app2 in load tag to use the tags defined in app1/custom_tags.py and app2/custom_tags.py as shown below:

# "templates/index.html"
                   #  ↓ ↓ Here ↓ ↓     ↓ ↓ Here ↓ ↓
{% load custom_tags app1.custom_tags app2.custom_tags %}

# ...

And, if there are the same tags like uppercase through multiple files as shown below:

# "core/templatetags/custom_tags.py"

@register.simple_tag
def uppercase(arg):
    return arg.upper()

# "core/templatetags/app1/custom_tags.py"

@register.simple_tag
def uppercase(arg):
    return arg.upper() + " app1"

# "core/templatetags/app2/custom_tags.py"

@register.simple_tag
def uppercase(arg):
    return arg.upper() + " app2"

Then, the uppercase tag of the last file set in load tag is used

# "templates/index.html"
                                    #  ↓ ↓ Here ↓ ↓
{% load custom_tags app1.custom_tags app2.custom_tags %}

{% uppercase "Hello World" %} # HELLO WORLD app2

Lastly, you can create multiple templatetags folders through multiple app folders app1 and app2 in addition to core folder as shown below:

django-project
 |-core
 |  |-settings.py
 |  └-templatetags # Here
 |     |-__init__.py
 |     └-custom_tags.py
 |-templates
 |  └-index.html
 |-app1
 |  └-templatetags # Here
 |     |-__init__.py
 |     └-custom_tags.py
 └-app2
    └-templatetags # Here
       |-__init__.py
       └-custom_tags.py

However, I recommend to create only one templatetags folder in core folder because there are 3 reasons as shown below:

1. It is easier to manage only one templatetags folder in core folder than managing multiple templatetags folders through multiple app folders.

2. For Django Admin, there is no folder to create templatetags folder so core folder is the most reasonable place to do it for Django Admin.

And, the 3rd reason is because through multiple templatetags folders, if there are multiple same name files like custom_tags.py as shown below:

django-project
 |-core
 |  |-settings.py
 |  └-templatetags
 |     |-__init__.py
 |     └-custom_tags.py # Here
 |-templates
 |  └-index.html
 |-app1
 |  └-templatetags
 |     |-__init__.py
 |     └-custom_tags.py # Here
 └-app2
    └-templatetags # Here
       |-__init__.py
       └-custom_tags.py # Here

Then, only one file is loaded in Django Templates but I don't know which file to be loaded according to my experiments as shown below:

# "templates/index.html"
                             
{% load custom_tags %} # I don't know which `custom_tags.py` is loaded. 

Answer 2

"weblog" after "load" (in template file django_website/templates/base_weblog.html) refers to file weblog.py in folder django_website/apps/blog/templatetags. Folder templatetags must be named exactly that and must contain a file named __init__.py (question 2).

"load" makes the custom template tags (render_latest_blog_entries and render_month_links in this case) available for use in templates, django_website\templates\base_weblog.html in this case. "Load" is a security and performance function.

Answer 3

load:

Load a custom template tag set.

See Custom tag and filter libraries for more information.