django-jsonfield-formatter 0.1.4

JSONEditor-based widget for Django admin JSONField with tree/code/view modes.

django-jsonfield-formatter

Installable Django app that replaces the default admin widget for JSONField with JSONEditor (tree, code, and view modes, search, navigation bar, and prettified editing).

Requirements

• Python 3.10+
• Django 4.2+

Install

pip install django-jsonfield-formatter

Or from a checkout:

pip install -e .

Setup

1. Add the app to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "jsonfield_formatter",
]

2. Run collectstatic in production so jsoneditor.min.js, jsoneditor.min.css, json_formatter_widget.css, and icons are available.

Usage in the admin

Option A — formfield_overrides

from django.contrib import admin
from django.db.models import JSONField

from jsonfield_formatter.widgets import JSONFormatterWidget


@admin.register(MyModel)
class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        JSONField: {"widget": JSONFormatterWidget},
    }

Option B — mixin

from django.contrib import admin

from jsonfield_formatter.admin import JSONFormatterAdminMixin


@admin.register(MyModel)
class MyModelAdmin(JSONFormatterAdminMixin, admin.ModelAdmin):
    pass

If you already use formfield_overrides, merge JSONField into your dict instead of using the mixin.

Widget options

JSONFormatterWidget accepts:

Argument	Description
attrs	Extra HTML attributes for the textarea (e.g. class).
mode	Initial mode: tree, code, or view (default tree).
height	CSS height for the editor area (default 400px).
editor_options	Dict merged into JSONEditor’s options (see JSONEditor API).
show_fullscreen_button	When True (default), shows Fullscreen so the editor can use the browser’s full screen; Escape exits.

Fullscreen

The widget adds a Fullscreen control above the editor. It calls the browser Fullscreen API on the editor panel so the JSON UI uses the whole display. JSONEditor is resized when entering or leaving fullscreen. To hide the button:

JSONFormatterWidget(show_fullscreen_button=False)

Saving

Before submit, the widget copies JSONEditor’s output into the hidden textarea. It prefers getText() (JSONEditor’s own JSON string) instead of parsing with get() and re-serializing with JSON.stringify, so large integers, key order, and other details are not altered by a JavaScript object round trip.

Root JSON null: Django’s JSONField turns the posted text "null" into Python None, which is usually wrong for default=dict or required fields. The widget coerces a root JSON null to {} before POST. If you need a real null root, set null=True on the model field and understand the admin may still normalize empty states to {} in edge cases—see CHANGELOG.md.

Example:

JSONFormatterWidget(
    mode="code",
    height="min(60vh, 520px)",
    editor_options={"sortObjectKeys": True},
)

Bundled JSONEditor version

Static files are vendored from jsoneditor 10.1.0 (see jsonfield_formatter/widgets.py).

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest