Document template-based widget rendering ramifications for contrib.gis

[Tobi]

After upgrading from 1.10.7 to 1.11, OSMGeoAdmin with custom map_template throws a TemplateDoesNotExist error.

Consider an OSMGeoAdmin and a simple view:

class FieldAdmin(OSMGeoAdmin):
    map_template = 'gis/admin/hello_world.html'

def test_view(request):
    return render(request, 'gis/admin/hello_world.html', {})

The template is in project_dir/templates/gis/admin/hello_world.html, and the relevant settings are pretty default:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'templates'),],
        'APP_DIRS': True,
        'OPTIONS': {
            ...
        },
    },
]

The test_view finds the template and renders fine, while the FieldAdmin cannot find the template. Interestingly, the filesystemloader is being used, but searches a completely wrong directory (ie definitely not my BASE_DIR):

django.template.loaders.filesystem.Loader: /home/ubuntu/env/lib/python3.5/site-packages/django/forms/templates/gis/admin/hello_world.html (Source does not exist)

Downgrading to 1.10.7 solves this issue.

[Tim Graham]

There's a backwards-incompatible change that needs to be documented. These widgets now use ​the form rendering API. You can fix your project by using the TemplatesSetting renderer.

[Tim Graham]

​PR

[GitHub <noreply@…>]

In 19a23fe:

Fixed #28074 -- Doc'd template-based widget rendering changes for contrib.gis.

[Tim Graham <timograham@…>]

In e217e15:

[1.11.x] Fixed #28074 -- Doc'd template-based widget rendering changes for contrib.gis.

Backport of 19a23fe562b4b2d051612d2850834c60177c4063 from master