1
Fork 0
With support for Wagtail 4.1
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.
Find a file
2023-02-20 11:00:31 +00:00
tests Fix tests by using lower case model name 2020-04-08 12:12:17 +05:30
wagtail_draftail_snippet Hacky "fix" for 4.1.1 support for now 2023-02-20 11:00:31 +00:00
.gitignore Test for Snippet Link Handler 2020-02-13 17:53:35 +05:30
.python-version upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00
.travis.yml upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00
CHANGELOG.md upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00
draftail-snippet-demo.gif Update demo gif (#10) 2020-04-17 16:12:32 -04:00
LICENSE Add BSD-3 license. 2020-01-17 14:10:32 -05:00
poetry.lock upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00
pyproject.toml upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00
pytest.ini Test for Snippet Link Handler 2020-02-13 17:53:35 +05:30
README.md Update readme. Bump to 0.4.1. 2022-05-26 11:20:16 -04:00
setup.py upgrading tests and required wagtail version (#26) 2022-10-27 17:13:59 -04:00

wagtail-draftail-snippet

Wagtail has support for adding numerous types of links to RichText content, but there is not a way to tie a link to an arbitrary snippet model currently. wagtail-draftail-snippet provides a way to create either an a href element for a specific snippet model based on a template that can be provided, or a completely free-form piece of HTML for a snippet.

The project provides the following draftail (Wagtail Richtext editor) features:

  1. snippet-link: Allows to create a link using the snippet chooser modal. The link is rendered using the template {app_name}/{model_name}_snippet_link.html.
  2. snippet-embed: Allows to embed a block using the snippet chooser modal. The block is embedded using the template {app_name}/{model_name}_snippet_embed.html.

Unsure whether you want to use a snippet link or embed? Embeds have complete flexibility, but 1) break the flow of text in the Draftail richtext editor and 2) can't be used to link arbitrary text. If you want to render a link to a snippet model inside of body copy, then you probably want to use the snippet link. For anything else, the embed can be used.

Demo of wagtail-draftail-snippet plugin

Install

  1. pip install wagtail-draftail-snippet
  2. Add wagtail_draftail_snippet to INSTALLED_APPS in Django settings
  3. Add "snippet-link" and "snippet-embed" to the features keyword list argument when instantiating a RichTextBlock, e.g. paragraph = RichTextBlock(features=["bold", "italic", "h1", "h2", "h3", "snippet-link", "snippet-embed"])
  4. 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_link.html and {app_name}/{model_name}_snippet_embed.html. For example, if you have an Affiliate snippet model in affiliates/models.py, then a file in affiliates/templates/affiliates/affiliate_snippet_link.html and affiliates/templates/affiliates/affiliate_snippet_embed.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_link.html could be the following.

<a href="{{ object.url }}" data-vars-action="content-cta" data-vars-label="{{ object.slug }}" rel="sponsored">

Requirements

The package requires Wagtail 2.5 or above.

Build the library

  1. poetry build

Push a new version release to PyPI

Travis-CI will build the library and deploy it to PyPI on every commit to master that is tagged with a version.

Run tests

  1. poetry install
  2. poetry run pytest

Contributors

License

BSD