Metadata-Version: 2.4
Name: django-jsonfield-formatter
Version: 0.1.3
Summary: JSONEditor-based widget for Django admin JSONField with tree/code/view modes.
Author: django-jsonfield-formatter contributors
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Django>=4.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# django-jsonfield-formatter

Installable Django app that replaces the default admin widget for `JSONField` with [JSONEditor](https://github.com/josdejong/jsoneditor) (tree, code, and view modes, search, navigation bar, and prettified editing).

## Requirements

- Python 3.10+
- Django 4.2+

## Install

```bash
pip install django-jsonfield-formatter
```

Or from a checkout:

```bash
pip install -e .
```

## Setup

1. Add the app to `INSTALLED_APPS`:

```python
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`**

```python
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**

```python
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](https://github.com/josdejong/jsoneditor/blob/master/docs/api.md)). |
| `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](https://developer.mozilla.org/en-US/docs/Web/API/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:

```python
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.

Example:

```python
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

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