Metadata-Version: 2.4
Name: portbay-django-stamper
Version: 0.1.0
Summary: Stamp Django templates with source coordinates for PortBay's visual editor
Author: PortBay
License-Expression: MIT
Project-URL: Documentation, https://docs.portbay.app/guides/visual-editor
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: Django>=4.2

# portbay-django-stamper

Stamps Django templates with `data-pb-loc="<path>:<line>:<col>"` so PortBay's
visual editor can resolve an element in the browser back to the exact tag in your
template source — which turns on precise mapping, structural editing, and style
edits that land in your source rather than an override sheet.

Development-only. Nothing is emitted unless `DEBUG` is on.

## Install

Install the package, then add `"portbay_loc"` to `INSTALLED_APPS`. That is the
whole install — it does not touch `TEMPLATES`, so your loaders and `APP_DIRS`
stay exactly as they are.

## Configuration

`PORTBAY_LOC` overrides the default in both directions — `PORTBAY_LOC=0` turns
stamping off with `DEBUG` on, `PORTBAY_LOC=1` turns it on with `DEBUG` off.
`manage.py runserver` passes the environment through, so the shell form is
enough.

## What is stamped

Elements written as literal markup in a `.html` template, including through
`{% include %}`, `{% extends %}`, `{% block %}` and `{% for %}` loops — each
template is stamped in its own source, so every fragment carries the coordinate
of the file it was written in.

Templates that are not `.html`, and templates with no file behind them, are never
touched. Attributes are only ever inserted, never removed or reordered, so the
worst failure mode is a missing stamp rather than a corrupted template.
