Metadata-Version: 2.4
Name: django-edit-away
Version: 0.1.0
Summary: Add your description here
Project-URL: Repository, https://github.com/AmericanPhilosophicalSociety/django-edit-away
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.10
Requires-Dist: django>=5.2.14
Requires-Dist: pillow>=12.2.0
Description-Content-Type: text/markdown

# django-edit-away
WIP exhibit crafter for Django for use in the digital humanities. At the moment, it provides a [Tiptap](https://tiptap.dev/) rich text editor with built-in support for embedding images and Youtube videos.

# Installation

TBD - right now, installing requires compiling the JavaScript dependencies via NPM. A fix is in the works.

Add ```django_edit_away``` to ```INSTALLED_APPS``` in ```settings.py```:

```
INSTALLED_APPS = [
    # ...
    'django_edit_away',
]
```
# Usage

Add ```TiptapField``` to your models:

```
from django.db import models
from django_edit_away.models import TiptapField


class Description(models.Model):
    body = TiptapField()
```

Under the hood, ```TiptapField``` stores data as a ```JSONField``` with two values, ```html``` and ```json_value```. The convenience wrapper ```django_edit_away.tiptap.Tiptap``` provides a ready-made object for holding this data in Python. HTML sanitization is handled via Tiptap. When you use a ```TiptapField``` in a form, the data is always saved from the JSON representation in the Tiptap editor, never from the HTML representation. This means it is only possible to directly modify the stored HTML via the Django shell or direct database access. More robust HTML sanitization for these circumstances is a future work plan.

## In forms

When using a Tiptap field in a form, it is necessary to call the ```form.media``` class to inject additional CSS and JavaScript:

```
<form id="guide-form" method="POST" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.media }}
    {{ form }}
    <button type="submit" class="btn btn-primary">Save</button>
</form>
```

## In templates

To display rich text content in a Django template outside of forms, call the field by its ```html``` element:

```
{{ object.my_tiptip_field.html|safe }}
```

Since the field stores the raw JSON representation, it is theoretically possible to implement a true WYSIWYG editor by calling a non-editable Tiptap instance, but there are no plans to implement this at present.

## Uploading images

To take advantage of the image upload feature, you must configure your [media settings](https://docs.djangoproject.com/en/6.0/howto/static-files/#serving-files-uploaded-by-a-user-during-development) and add ```django_edit_away.urls``` to your url configuration:

```
from django.urls import path, include

url_patterns = [
    # ...
    path('', include('django_edit_away.urls)),
]
```

The AJAX requests that make image uploads work expect the urlconf to be served from root, so it is essential to follow this configuration exactly. The path ```/image-upload``` should be considered a reserved path for projects using this package.

Uploaded and embedded images can have either the class ```.inline-ref``` or ```.parallax-ref```. The styling of these classes is left to the user, but we hope to provide sample styling in the near future.

## Embedding Youtube videos

To get embedded Youtube videos to work, you must add the following to ```settings.py```:

```
SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin'
```
