Django Integration

Usage in Django

loc_authorities provides a minimal Django integration that enables a lookup field in forms. This can be used either in the Django admin or in your own form. Intentionally, the integration only affects form behavior. Integration with model fields is left up to the user.

The form field autocomplete will display the authoritative label as retrieved from the Library of Congress API. When the user selects a label, it will populate to the form field as the URI. The model field used should therefore be capable of storing the URI (e.g. CharField, URIField with the appropriate transformation). If you want to save both the label and the URI to the database, you could use the API features of loc_authorities to retrieve the label and save it to another field through, for instance, a custom save method. This could be applied to any other property, including those retrieved via LocEntity.rdf.

Installation and Configuration

To configure loc_authorities for usage with Django, you must install loc_authorities with the optional Django dependencies.

Install into a virtual environment with pip:

(.venv) $ pip install loc-authorities[django]

Alternatively, install with uv:

$ uv add loc-authorities --group django

To use loc_authorities with Django, you must add loc_authorities and its dependencies from django-autocomplete-light to the installed applications in your project’s settings.py file. If you intend to use this in the Django admin interface, it must be added before django.contrib.admin:

INSTALLED_APPS = [
    ...
    'dal',
    'dal_alight',
    'loc_authorities',
    'django.contrib.admin',
    ...
]

Include the :code`loc-authorities` URLs at the preferred base URL in urls.py:

urlpatterns = [
    ...
    path(r'loc-authorities/', include('loc_authorities.urls', namespace='loc-authorities')),
    ...
]

Use in standard forms

To use loc_authorities in a standard form, use the provided LocField on your form:

from django import forms
from loc_authorities.forms import LocField

class MyForm(forms.ModelForm):
    uri = LocField()

    class Meta:
        model = MyModel
        fields = ('title', 'uri')

By default, the provided field will query the url loc-authorities:suggest. If you have configured your URLs differently or if you want to query a different service, you need to explicitly pass that URL to the widget:

from django import forms
from loc_authorities.forms import LocField, LocWidget

class MyForm(forms.ModelForm):
    uri = LocField(
        widget=LocWidget(url='loc-authorities:subject-search'),
    )

    class Meta:
        model = MyModel
        fields = ('title', 'uri')

Then in the template, it is necessary to include {{ form.media }} to load the required JavaScript:

{% extends 'base-html' %}
{% load static %}

{% block content %}
  <form action="" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit">
  </form>
  {{ form.media }}
{% endblock %}

Use in the Django Admin

To use loc_authorities in the Django admin, create a custom form as described above and then register it in the admin.

from django.contrib import admin

from .models import MyModel
from .forms import MyForm


class MyModelAdmin(admin.ModelAdmin):
    form = MyForm

admin.site.register(MyModel, MyModelAdmin)