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

Yet another bookmarking library (yabl) for Django. Bookmark and tag arbitrary models. Modals launched with htmx.
https://github.com/justmars/django-yabl

Last synced: 3 days ago
JSON representation

Yet another bookmarking library (yabl) for Django. Bookmark and tag arbitrary models. Modals launched with htmx.

• Host: GitHub
• URL: https://github.com/justmars/django-yabl
• Owner: justmars
• License: bsd-3-clause
• Created: 2021-12-09T11:31:27.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2023-05-16T17:11:35.000Z (over 1 year ago)
• Last Synced: 2024-10-08T17:21:57.184Z (about 1 month ago)
• Language: Python
• Homepage:
• Size: 142 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# django-yabl

Yet another bookmarking library (yabl) for Django. Bookmark and tag arbitrary models using a `AbstractBookmarkable` on user-created models. This enables these inheriting "child" (concrete) models – e.g. _Movies, Books, Laws, Clothes, etc._ – to have automatically generated properties for bookmarking and tagging of users with an existing account. In other words: the abstraction makes each inheriting instance _bookmarkable_ and _taggable_ by authenticated users.

## The `bookmarks` field

Each inheriting model will contain a `bookmarks` field. This 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`

## The `AbstractBookmarkable` attributes & methods

| 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`.