Templates

This document describes how to use templates with Django Bread.

Template Context

In addition to the context variables that Django Vanilla Views provides, Django Bread provides the following to all of your templates:

Variable             Description
--------             -----------
bread                Bread object
verbose_name         Model's verbose_name field
verbose_name_plural  Model's verbose_name_plural field
base_template        The default base_template that should be extended.
may_{action}         (i.e. may_browse, may_read, etc.) Boolean describing whether user has specified permission

Certain action views provide some additional variables. The Browse view has columns and filter. The Read view has form.

Override get_context_data to change the variables provided to your template:

class MyBrowseView(BrowseView):
    def get_context_data(self, **kwargs):
        data = super(BrowseView, self).get_context_data(**kwargs)
        data['my_special_var'] = 42
        return data

Template Resolution

There are various ways to configure how and in what order Django Bread searches for the proper template for your view.

By default, each Django Bread view will search first in an app-specific location (described below), and then fall back to the templates provided by the Django Bread package.

App-specific location

The app-specific location is described by this pattern: {app_label}/{model}_{view}.html. For example, if your app’s name is MyApp and your model’s name is MyModel, Django Bread will look for a browse template in myapp/mymodel_browse.html.

Customization

There are 3 ways that you can customize this behavior even further:

1. Specify template_name_pattern in your Bread object. All views in that Bread object will then search in the app-specific location first (described above), then search template_name_pattern, and then fall back to the Django Bread provided templates. The value supplied to template_name_pattern is a string that can take zero or more placeholders with the names app_label, model, or view. An example of a valid pattern would be '{app_label}/special_{model}_{view}.html'. Note that you can use this technique to implement site-wide customization by creating a subclass of Bread with template_name_pattern set, and then use that subclass (or children of it) throughout your site.

2. Set the template_name attribute in your View to the exact template that you want for that view. Example:

   class MyBrowseView(BrowseView):
       template_name = 'my/special-location.html'
   

3. Override get_template_names in a specific action View. This method should return a tuple of strings representing template locations to search. In most cases, using #3 is a simpler way to achieve this. But if you have a situation where you need a list of templates to be searched then here is an example on how to do that:

   class MyBrowseView(BrowseView):
       def get_template_names(self):
           return ('my/special-location.html', )
   

In addition to these template resolution rules, it’s important to remember Django’s own default rules. If you have a template with the same name in 2 different applications, then whichever app is listed first in INSTALLED_APPS wins. So, another way to get site-wide customization without using #2 above is to create templates named bread/{activity}.html in one of your local apps and make sure it’s listed before bread.

Caveat

We mentioned above that each View is matched to a template with the same name (BrowseView -> ‘…browse.html’). This is true for everything except the AddView. Because add and edit templates are so similar, the AddView connects to the ‘edit.html’ template. There is no ‘add.html’ template. If you need your AddView to have its own template, there are 2 ways you can accomplish this. Either use methods #3 or #4 above, or set template_name_suffix in your AddView class. It defaults to _edit, but if you change it to _add then your AddView will be linked to a {app_label}/{model}_add.html template instead.