Metadata-Version: 2.1
Name: django-yabl
Version: 0.0.9
Summary: Yet another bookmarking library (yabl) for Django. Bookmark and tag arbitrary models.
Home-page: https://github.com/justmars/django-yabl
License: MIT
Author: Marcelino G. Veloso III
Author-email: mars@veloso.one
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: Django (>=4.0,<5.0)
Requires-Dist: django-debug-toolbar (>=3.2.2,<4.0.0)
Requires-Dist: django-extensions (>=3.1.5,<4.0.0)
Project-URL: Repository, https://github.com/justmars/django-yabl
Description-Content-Type: text/markdown

# django-yabl

Yet another bookmarking library (yabl) for Django. Bookmark and tag arbitrary models.

`AbstractBookmarkable` contains `bookmarks` field. This enables arbitrary child models, e.g. Movies, Books, Laws, Clothes, etc., to inherit uniform properties for bookmarking and tagging.

The `bookmarks` field is mapped to a generic `Bookmark` model containing:

1. the authenticated user adding the bookmark, i.e. the `bookmarker`;
2. the concrete model instance referenced, i.e. the _bookmarked_;[^1] and
3. a ManyToMany `tags` field which maps to a `TagItem` model.

[^1]: The model is referenced via a `content_type` and an `object_id`

## AbstractBookmarkable

The abstraction makes each inheriting instance _bookmarkable_ and _taggable_ by authenticated users.

| Attributes                        | Purpose                                                    |
| --------------------------------- | ---------------------------------------------------------- |
| `is_bookmarked`(user)             | Check whether object instance is bookmarked or not         |
| `get_bookmarked`(user)            | Get instances of model that user has bookmarked            |
| `get_user_tags`(user)             | If user bookmarked, get user-made tags on instance         |
| `toggle_bookmark`(user)           | Toggle bookmark status as bookmarked or not                |
| `add_tags`(user, tags: list[str]) | Add unique tags, accepts a list of names                   |
| `remove_tag`(user, tag: str)      | Delete an existing tag name from tags previously added     |
| `set_bookmarked_context`(user)    | Combines relevant urls and attributes for template output  |
| @`modal`                          | Custom modal enables: _toggle_, _add tags_, _remove tag_   |
| @`launch_modal_url`               | URL to launch custom modal                                 |
| @`get_item_url`               | URL to load the panel containde within custom modal                                 |
| @`add_tags_url`                   | URL to POST tags added                                     |
| @`del_tag_url`                    | URL to DELETE tag added                                    |
| @`toggle_status_url`              | URL to toggle bookmark status of an object instance added  |
| @`object_content_for_panel`       | Content when custom modal is loaded; **must** be overriden |

## Modal-based UX

### What is the concept?

The modal is where the user interacts – i.e. toggle bookmark status, add tags, remove tag (see table above) – with the data.

### How is the modal styled?

See the htmx/hyperscript example [modal.css](bookmarks/static/css/modal.css).

### How is the modal constructed during run-time?

See _app-level_ [modal.html](bookmarks/templates/commons/modal.html) which shows a modal via htmx click on the `@launch_modal_url` property.

### What are the pre-made contents of the modal?

The _app-level_ [panel.html](bookmarks/templates/tags/templates/tags/panel.html), contained within the modal, shows an actionable form for saving the bookmarable object and associating said object with tags:

1. The submission of tags is POST'ed through the `add_tags_url`.
2. The deletion of tags is DELETE'ed through the `del_tag_url`.
3. The bookmark toggle is PUT'ed through the `toggle_status_url`.

## Setup

1. Download and [install](bookmarks/docs/setup.md).
2. See [configuration](bookmarks/docs/configure.md) of models to be bookmarked and tagged.
3. Examine [frontend](bookmarks/docs/frontend.md) setup using `htmx/hyperscript`.

