Metadata-Version: 2.4
Name: wagtail-pagetree
Version: 0.3.1
Summary: Lazy-loaded virtualized page tree for the Wagtail admin
Author: Hyperlocal HQ
License-Expression: MIT
Project-URL: Repository, https://github.com/hyperlocalhq/wagtail-pagetree
Project-URL: Bug Tracker, https://github.com/hyperlocalhq/wagtail-pagetree/issues
Keywords: wagtail,django,admin,page-tree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 6
Classifier: Framework :: Wagtail :: 7
Classifier: Framework :: Wagtail :: 8
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: wagtail>=6.3
Provides-Extra: localize
Requires-Dist: wagtail-localize>=1.10; extra == "localize"
Dynamic: license-file

# wagtail-pagetree

Lazy-loaded, virtualised page tree for the [Wagtail](https://wagtail.org) admin.

Ships a single admin viewset (`pagetree:index`) that renders a fast, locale-aware
explorer over `wagtail.models.Page`. The tree loads children on demand via JSON
endpoints, supports drag-and-drop reordering with cascade translations,
context menu and bulk actions, respects `PagePermissionPolicy`, and scales to
large trees (P95 < 200 ms for 500-page corpora).

The tree remembers open branches, search and filters per browser tab, and
admin actions started from it (edit, add, copy, delete …) return to it with
the page revealed. Every page's header menu gets a **Show in Page Tree**
action, and the column header shows each locale's translation coverage.

![Page Tree in the Wagtail admin: German primary tree with per-locale status dots and the row menu open](https://raw.githubusercontent.com/hyperlocalhq/wagtail-pagetree/main/docs/page-tree.png)

## Install

```bash
uv add wagtail-pagetree            # or: pip install wagtail-pagetree
uv add "wagtail-pagetree[localize]"  # with wagtail-localize integration
```

Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "wagtail",
    "wagtail_pagetree",
    # ...
]
```

The viewset auto-registers via `wagtail_hooks.py`. Restart your dev server and
look for **Page Tree** in the admin sidebar.

[wagtail-localize](https://github.com/wagtail/wagtail-localize) is optional.
When installed, the tree flags out-of-date translations and links to its
sync / translate views; without it those features are simply absent.

## Requirements

- Python 3.10 – 3.14
- Django 4.2, 5.2, 6.0, 6.1
- Wagtail 6.3, 7.0, 8.0

## Translations

The admin UI ships English and German. Catalogs live in
`src/wagtail_pagetree/locale/<lang>/LC_MESSAGES/`:

- `django.po` — Python and template strings
- `djangojs.po` — the React frontend, served by the viewset's own
  `JavaScriptCatalog` (`pagetree:jsi18n`)

```bash
scripts/makemessages.sh          # re-extract every existing locale
scripts/makemessages.sh fr       # add a new locale
scripts/makemessages.sh --compile
```

## Development

```bash
uv sync                          # dev environment (pytest, tox, wagtail-localize)
uv run pytest                    # test suite against tests/settings.py (SQLite)
uv run pytest --cov              # with coverage
uv run pytest -m bench -s        # opt-in benchmarks
uv run tox run-parallel          # full Python × Django × Wagtail matrix

# rebuild the JS bundle after editing frontend/src/
cd frontend
npm install
npm run build
npm run check                    # drift gate: committed bundle must match source
```

## Release

1. Bump the version in `pyproject.toml` and `src/wagtail_pagetree/__init__.py`.
2. Commit, then tag and push: `git tag v0.1.0 && git push origin v0.1.0`.

The `Release` workflow runs the test matrix, builds, publishes to TestPyPI,
then PyPI (trusted publishing, no stored token) and creates a GitHub release.
It refuses to publish when the tag and the two version strings disagree.

## Layout

```
├── pyproject.toml
├── tox.ini
├── src/wagtail_pagetree/        # the Django app
│   ├── apps.py
│   ├── viewsets.py              # registers the admin viewset + JS catalog
│   ├── views.py                 # tree, children, bulk, move endpoints
│   ├── wagtail_hooks.py         # @hooks.register("register_admin_viewset")
│   ├── services/                # tree, presenters, permissions, locale, search, bulk, move, translations
│   ├── locale/                  # django.po / djangojs.po
│   ├── templates/wagtail_pagetree/page_tree.html
│   └── static/wagtail_pagetree/{css,js}/...
├── frontend/                    # React/JSX source for bundle.js (esbuild)
├── scripts/makemessages.sh
└── tests/                       # settings.py, urls.py, testapp/ + test modules
```

## License

MIT.
