https://github.com/justmars/django-highlights

Custom javascript in selection of text as Highlight, subsequently saved as generic model via htmx.
https://github.com/justmars/django-highlights

Last synced: 3 days ago
JSON representation

Custom javascript in selection of text as Highlight, subsequently saved as generic model via htmx.

• Host: GitHub
• URL: https://github.com/justmars/django-highlights
• Owner: justmars
• License: bsd-3-clause
• Created: 2021-12-13T16:11:18.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2023-05-16T16:47:01.000Z (over 1 year ago)
• Last Synced: 2024-10-06T09:09:54.352Z (about 1 month ago)
• Language: Python
• Homepage:
• Size: 225 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# django-highlights

Add a generic relation `Highlight` to arbitrary models.

1. Selecting the highlight is done with custom javascript.

2. Saving the highlightted snippet (without page refresh) is done with `htmx` with a dash of `hyperscript` for dealing with the return trigger.

## Setup

### Install

```zsh

.venv> poetry add django-highlights # pip3 install django-highlights

```

### Add app to project settings

```python

# in project_folder/settings.py

INSTALLED_APPS = [..., "highlights"]

```

### Add highlight model to database

```zsh

.venv> python manage.py migrate

```

## Configuration

### Initialize model

Ensure model, e.g. `Sentinel`, with:

1. a _unique_ SlugField named `slug` - this will be used for creating the `highlight url`

2. a TextField, e.g. `content`/`description` - this is the field that will be _highlightable_

### Add mixin

Make the initialized model inherit from the `AbstractHighlightable` abstract base model :

```python

from django_extensions.db.models import TitleSlugDescriptionModel

from highlights.models import AbstractHighlightable  # import

class Sentinel(TitleSlugDescriptionModel, AbstractHighlightable):  # add

    pass

```

Each `Sentinel` instance, i.e. pk=1, pk=2, etc., will now have generic relations to a `Highlight` model and have access to a pre-named, `slug`-based `highlight_url`. The `Sentinel` class will now have a `@highlight_path` property to be used in `urlpatterns` so that each instances `highlight_url` is recognized by the project.

### Setup url

```python

# sentinels/urls.py

from .apps import (

    SentinelsConfig,

)  # already built when you previously created `sentinels` via python manage.py startapp sentinels

from .models import Sentinel

app_name = SentinelsConfig.name  # new

urlpatterns = [Sentinel.highlight_path, ...]  # new

```

### Use article id with highighter and notice

```jinja

    
Title: {{ object.title }}


    

    

        {{object.description}}

    

{% if user.is_authenticated %}

    

    


        


            


                Highlight added!

                

            

        

    


    

    {% load highlighter %}

    {% highlight_btn_show url=object.highlight_url %}

{% endif %}

```

## Flow

1. The `` tag will contain the `scope` or the highlightable text field.

2. The `` will contain the `url` or the submission of highlights to the server.

3. The specific DOM nodes have event listeners found in `textSelector.js`.

4. Any text selection inside the scoped `` will reflect in the ``'s hidden ``.

5. When highlight `maker` is ready with text selection, click on footer `` submits highlight stored in ``.

6. The submission is done through `htmx`'s `hx-post` without refreshing or swapping content, i.e. a POST request is sent to the `save_highlight` view c/o the passed `highlight_url`.

7. The request adds a new `Highlight` (from an authenticated highlight `maker`) to the highlightable model instance, e.g. Sentinel pk=2.

8. The successful POST request sends a header trigger to the client to alert the `maker`.