Django: What's the use of the context_instance parameter in the render shortcut function?

Question

Documentation on 'Render' shortcut

According to the link above, the context_instance parameter is defined as

The context instance to render the template with. By default, the template will be rendered with a RequestContext instance (filled with values from request and dictionary).

With this definition in mind, I don't see any scenarios that would benefit from supplying the context_instance argument. I mean if I need to provide additional context values I would just add them to the dictionary parameter. I don't know how context_instance can be useful. Please educate me. Thanks.

Answer 1

The main scenario is to make certain variables available in your template. For example, the auth context processor makes (amongst others) the user variable available for use in your template so that you don't have to pass it yourself. Although it's quite a big paragraph, the Django documentation does quite a good job at explaining it.

In a nutshell: by adding context_instance=RequestContext(request) to your render call, all processors defined in your settings.py (under the TEMPLATE_CONTEXT_PROCESSORS variable) are executed in order. Each of these processors return a dict with variables that are made available in the template. Using the default set, this means you do not have to add e.g. the user, csrf or messages variables yourself: this is done by the processors.

An example for own context processor would be to add your main menu parameters to the template. Say you want to highlight the menu for the current category the user is viewing: by creating your own context processor that determines the current location, it could add some variables in the template that are used by your menu to do the highlighting.

Answer 2

Context instance is now deprecated in Django 1.8, and dictionary has been renamed to context.

Changed in Django 1.8:
The context argument used to be called dictionary. That name is deprecated in Django 1.8 and will be removed in Django 2.0.

Deprecated since version 1.8:
The context_instance argument is deprecated. Simply use context.

So if you're using a more recent version of Django, your call to the Render function should be:

from django.shortcuts import render

def my_view(request):
    # View code here...
    return render(request, 'myapp/index.html', {"foo": "bar"},
        content_type="application/xhtml+xml")

Where {"foo": "bar"} is your context. The missing context_instance is (I presume) created by default now and populated with the required context of your request.

Answer 3

I can think of two things:

1. Backwards compatibility. You can safely change all references from render_to_response to render.

2. You don't want the context processors to be run for that particular view, you can pass in None in the context_instance (saves a bit of overhead.)