1
Fork 0
This repository has been archived on 2024-07-16. You can view files and clone it, but cannot push or open issues or pull requests.
wagtail-draftail-snippet/README.md

44 lines
2.3 KiB
Markdown
Raw Normal View History

2020-01-08 04:41:21 +00:00
# wagtail-draftail-snippet
2020-01-14 18:51:05 +00:00
Wagtail has support for adding numerous types of links to `RichTextBlock` content, but there is not a way to tie a link to an arbitrary `snippet` model currently. `wagtail-draftail-snippet` provides a way to add a new button to the Draftail rich text editor, which creates an `a href` element for a specific `snippet` model based on a template that can be provided.
2020-01-08 04:41:21 +00:00
2020-02-11 19:54:50 +00:00
![Demo of wagtail-draftail-snippet plugin](https://i.imgur.com/pyX25hg.gif)
2020-01-08 04:41:21 +00:00
## Install
2020-02-11 19:54:50 +00:00
1. `pip install wagtail-draftail-snippet`
2020-01-08 04:41:21 +00:00
1. Add `wagtail_draftail_snippet` to `INSTALLED_APPS` in Django settings
1. Add `"snippet"` to the `features` keyword list argument when instantiating a `RichTextBlock`, e.g. `paragraph = RichTextBlock(features=["bold", "italic", "h1", "h2", "h3", "snippet"])`
1. Create a frontend template to determine how the snippet model will be rendered. Frontend templates are required for a snippet to be selected and are discovered when they match a path like `{app_name}/{model_name}_snippet.html`. For example, if you have an `Affiliate` snippet model in `affiliates/models.py`, then a file in `affiliates/templates/affiliates/affiliate_snippet.html` would be required.
## Example use-case
Wagtail is used for a content site that will display articles that have affiliate links embedded inside the content. Affiliate links have a snippet data model to store information with a URL, start, and end dates; the urls need to be rendered in such a way that JavaScript can attach an event listener to their clicks for analytics.
When the content gets rendered, it uses the specific affiliate model to get the URL stored in the snippet model. If the affiliate's URL ever changes, the snippet can be changed in the Wagtail admin, and the all of the content will use the correct link when rendered.
An example frontend template in `affiliates/templates/affiliates/affiliate_snippet.html` could be the following.
```
<a href="{{ object.url }}" data-vars-action="content-cta" data-vars-label="{{ object.slug }}" rel="sponsored">
```
2020-02-12 10:10:03 +00:00
## Requirements
The package requires Wagtail 2.5 or above.
2020-01-08 04:41:21 +00:00
2020-01-17 19:10:32 +00:00
## Build the library
2020-01-08 04:41:21 +00:00
1. `poetry build`
## Contributors
- [Parbhat Puri](https://github.com/Parbhat)
- [Adam Hill](https://github.com/adamghill/)
2020-01-17 19:10:32 +00:00
## License
[BSD](https://github.com/themotleyfool/wagtail-draftail-snippet/blob/master/LICENSE)