| Name | wagtail-f-richtext JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | An alternative Wagtail richtext filter that applies classes or styles to rich text HTML content. |
| upload_time | 2024-07-14 20:29:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2022, Nick Moreton Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
wagtail
richtext
filter
html
class
style
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# Wagtail F Richtext
[](https://github.com/nickmoreton/wagtail-f-richtext/actions/workflows/test.yml)
An alternative Wagtail `richtext` filter that can be configured in your apps settings.
It can parse the content in a RichText field in the same way the Wagtail richtext filter works and add classes or inline styles to the HTML.
Once the package is added to your Wagtail site, add one or two pieces of configuration to your settings then use the `f_richtext` template tag where you want the css classes or inline styles added to the HTML content.
It's especially useful if you are including a CSS framework such as:
- [Bulma](https://bulma.io)
- [CodyHouse](https://codyhouse.co)
- [Tachyons](https://tachyons.io)
- [Tailwind](https://tailwindcss.com)
- other frameworks are available :)
## Installation
Install the package into your python environment.
```bash
pip install wagtail-f-richtext
```
Add the package to your INSTALLED_APS
```python
"wagtail_f_richtext"
```
Any css framework styles will need to be installed before you will see any style changes for richtext content. If you are using only the inline styles you should see the effect of them applied when a page is viewed.
## Using the f_richtext filter
The `f_richtext` filter can be used in your templates in the same way as the Wagtail core provided `richtext` filter.
First add the filter to your template.
```html
{% load wagtail_f_richtext %}
```
Then use it in your template.
### with a RichText field
- `{{ page.body|f_richtext:"framework" }}` will add classes to the HTML tags
- `{{ page.body|f_richtext:"inline_styles" }}` will add inline styles to the HTML tags
### with a RichText block
- `{{ value|f_richtext:"framework" }}` will add classes to the HTML tags
- `{{ value|f_richtext:"inline_styles" }}` will add inline styles to the HTML tags
*You can use it without a parameter `{{ page.body|f_richtext }}` and it will work just like the Wagtail core provided filter (not required)*
Sample `framework` rendered
```html
<div class="text-component">
<p data-block-key="92eli">A paragraph <b class="font-bold">Vulputate Vestibulum</b> <i class="font-italic">Commodo</i></p>
<h2 class="heading-2" data-block-key="fkden">Heading 2</h2>
<ul class="list list--ul">
<li data-block-key="fe5cv">UL List Item 1</li>
<li data-block-key="6ort3">UL List Item 2</li>
</ul>
<ol class="list list--ol">
<li data-block-key="d5s3r">OL List Item 1</li>
<li data-block-key="5l47j">OL List Item 2</li>
</ol>
<img alt="IMG_4511" class="f-richtext-image f-richtext-image--right" height="375" src="/media/images/IMG_4511.width-500.jpg" width="500">
<div style="clear: both;"></div>
</div>
```
Sample `inline_styles` rendered
```html
<div style="overflow:hidden;">
<p data-block-key="92eli" style="margin-bottom: 1em;">A paragraph <b style="font-weight: bold;">Vulputate Vestibulum</b> <i style="font-style: italic;">Commodo</i></p>
<h2 data-block-key="fkden" style="margin-bottom: 1em;">Heading 2</h2>
<ul style="float: none; clear: both; list-style: disc; margin-left: 2em; margin-bottom: 1em;">
<li data-block-key="fe5cv">UL List Item 1</li>
<li data-block-key="6ort3">UL List Item 2</li>
</ul>
<ol style="float: none; clear: both; list-style: decimal; margin-left: 2em; margin-bottom: 1em;">
<li data-block-key="d5s3r">OL List Item 1</li>
<li data-block-key="5l47j">OL List Item 2</li>
</ol>
<img alt="IMG_4511" class="richtext-image right" height="375" src="/media/images/IMG_4511.width-500.jpg" style="float: right; margin-left: 1rem; margin-right: 0; margin-bottom: 1rem; height: auto;" width="500">
<div style="clear: both;"></div>
</div>
```
## Configuration
You need to add one or both of these settings to your apps settings.
- `F_RICHTEXT_FRAMEWORK_CONFIG`
- `F_RICHTEXT_INLINE_CONFIG`
### Example for adding classes to HTML tags
```python
F_RICHTEXT_FRAMEWORK_CONFIG = {
# target html tags
"classes": {
"h1": "heading-1",
"h2": "heading-2",
"ul": "list list--ul",
"ol": "list list--ol",
"a": "color-contrast-higher",
"b": "font-bold",
"i": "font-italic",
},
# wrap the richtext content with a class
"wrapper_classes": [
"text-component",
],
# swap the richtext image alignment classes
"alignment_classes": {
"richtext-image left": "f-richtext-image f-richtext-image--left",
"richtext-image right": "f-richtext-image f-richtext-image--right",
"richtext-image full-width": "margin: 1em 0; width: 100%; height: auto;",
},
# remove any empty HTML tags (blank lines in the richtext editor)
"remove_empty_tags": [
"p",
],
# add a clearfix to the end of the content
"append_clearfix": True,
}
```
### Example for adding inline styles
```python
F_RICHTEXT_INLINE_CONFIG = {
# target html tags
"styles": {
"h1": "margin-bottom: 1em;",
"h2": "margin-bottom: 1em;",
"h3": "margin-bottom: 1em;",
"h4": "margin-bottom: 1em;",
"h5": "margin-bottom: 1em;",
"h6": "margin-bottom: 1em;",
"p": "margin-bottom: 1em;",
"ul": "float: none; clear: both; list-style: disc; margin-left: 2em; margin-bottom: 1em;",
"ol": "float: none; clear: both; list-style: decimal; margin-left: 2em; margin-bottom: 1em;",
"code": "font-family: monospace; background-color: #f5f5f5; padding: 0.25rem 0.5rem;",
"sub": "vertical-align: sub; font-size: smaller;",
"sup": "vertical-align: super; font-size: smaller;",
"div": "float: none; clear: both;",
"iframe": "max-width: 100%; width: 720px; height: 400px; margin-top: 1em; margin-bottom: 1em;",
"b": "font-weight: bold;",
"i": "font-style: italic;",
},
# wrap the richtext content with a style
"wrapper_styles": [
"overflow:hidden;",
],
# swap the richtext image alignment classes for an inline style
"alignment_styles": {
"richtext-image left": "float: left; margin-right: 1rem; margin-left: 0; margin-bottom: 1rem; height: auto;",
"richtext-image right": "float: right; margin-left: 1rem; margin-right: 0; margin-bottom: 1rem; height: auto;",
"richtext-image full-width": "margin: 1em 0; width: 100%; height: auto;",
},
# remove any empty HTML tags (blank lines in the richtext editor)
"remove_empty_tags": [
"p",
],
# add a clearfix to the end of the content
"append_clearfix": True,
}
```
## Optional usage
### Use your own parser class
The parser class can be extended to add your own parsing requirements.
Create your own class that inherits from [fRichTextParser](./wagtail_f_richtext/parser.py) and add the following to your apps settings.
```python
F_RICHTEXT_PARSER_CLASS="the.dotted.path.to.your.own.Class"
```
### Use your own runner function
The order of the parsing and loading of your configuration is done in the runner method that is called by the `f_richtext` filter.
Create your own [runner function](./wagtail_f_richtext/parser.py#L102) in a suitable place and add the following settings to your app.
```python
F_RICHTEXT_PARSER_RUNNER="the.dotted.path.to.your.own.function"
```
## Contributing
The test app can be run to develop your contribution.
1. Fork the repo and clone it to your computer.
2. Change to the folder where you cloned it to.
Create a virtual environment and install the dependencies:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[development,testing]"
# run the migrations, add an admin account and start the app
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
```
Then you can view the app at <http://localhost:8000> and login to the admin at <http://localhost:8000/admin>
Run the tests:
```bash
python manage.py test
```
You can use shortcuts in the [Makefile](./Makefile) to run the above commands.
```bash
make setup
```
will run all the above initial commands and creates a superuser with login credentials Username: `admin` Password: `admin`
## Supports
- Wagtail 4.1, 4.2, 5.0, 5.1. 5.2, 6.0
- Django 3.2, 4.0, 4.1, 4.2
- Python 3.8, 3.9, 3.10, 3.11, 3.12
Raw data
{
"_id": null,
"home_page": null,
"name": "wagtail-f-richtext",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "wagtail, richtext, filter, html, class, style",
"author": null,
"author_email": "Nick Moreton <nickmoreton@me.com>",
"download_url": "https://files.pythonhosted.org/packages/57/ab/1b29c7a462c9bf33a8e2c250691439d32c82f9d51d94e14e3914f91b9f73/wagtail_f_richtext-1.1.0.tar.gz",
"platform": null,
"description": "# Wagtail F Richtext\n\n[](https://github.com/nickmoreton/wagtail-f-richtext/actions/workflows/test.yml)\n\nAn alternative Wagtail `richtext` filter that can be configured in your apps settings.\n\nIt can parse the content in a RichText field in the same way the Wagtail richtext filter works and add classes or inline styles to the HTML.\n\nOnce the package is added to your Wagtail site, add one or two pieces of configuration to your settings then use the `f_richtext` template tag where you want the css classes or inline styles added to the HTML content.\n\n It's especially useful if you are including a CSS framework such as:\n\n- [Bulma](https://bulma.io)\n- [CodyHouse](https://codyhouse.co)\n- [Tachyons](https://tachyons.io)\n- [Tailwind](https://tailwindcss.com)\n- other frameworks are available :)\n\n## Installation\n\nInstall the package into your python environment.\n\n```bash\npip install wagtail-f-richtext\n```\n\nAdd the package to your INSTALLED_APS\n\n```python\n\"wagtail_f_richtext\"\n```\n\nAny css framework styles will need to be installed before you will see any style changes for richtext content. If you are using only the inline styles you should see the effect of them applied when a page is viewed.\n\n## Using the f_richtext filter\n\nThe `f_richtext` filter can be used in your templates in the same way as the Wagtail core provided `richtext` filter.\n\nFirst add the filter to your template.\n\n```html\n{% load wagtail_f_richtext %}\n```\n\nThen use it in your template.\n\n### with a RichText field\n\n- `{{ page.body|f_richtext:\"framework\" }}` will add classes to the HTML tags\n- `{{ page.body|f_richtext:\"inline_styles\" }}` will add inline styles to the HTML tags\n\n### with a RichText block\n\n- `{{ value|f_richtext:\"framework\" }}` will add classes to the HTML tags\n- `{{ value|f_richtext:\"inline_styles\" }}` will add inline styles to the HTML tags\n\n*You can use it without a parameter `{{ page.body|f_richtext }}` and it will work just like the Wagtail core provided filter (not required)*\n\nSample `framework` rendered\n\n```html\n<div class=\"text-component\">\n <p data-block-key=\"92eli\">A paragraph <b class=\"font-bold\">Vulputate Vestibulum</b> <i class=\"font-italic\">Commodo</i></p>\n <h2 class=\"heading-2\" data-block-key=\"fkden\">Heading 2</h2>\n <ul class=\"list list--ul\">\n <li data-block-key=\"fe5cv\">UL List Item 1</li>\n <li data-block-key=\"6ort3\">UL List Item 2</li>\n </ul>\n <ol class=\"list list--ol\">\n <li data-block-key=\"d5s3r\">OL List Item 1</li>\n <li data-block-key=\"5l47j\">OL List Item 2</li>\n </ol>\n <img alt=\"IMG_4511\" class=\"f-richtext-image f-richtext-image--right\" height=\"375\" src=\"/media/images/IMG_4511.width-500.jpg\" width=\"500\">\n <div style=\"clear: both;\"></div>\n</div>\n```\n\nSample `inline_styles` rendered\n\n```html\n<div style=\"overflow:hidden;\">\n <p data-block-key=\"92eli\" style=\"margin-bottom: 1em;\">A paragraph <b style=\"font-weight: bold;\">Vulputate Vestibulum</b> <i style=\"font-style: italic;\">Commodo</i></p>\n <h2 data-block-key=\"fkden\" style=\"margin-bottom: 1em;\">Heading 2</h2>\n <ul style=\"float: none; clear: both; list-style: disc; margin-left: 2em; margin-bottom: 1em;\">\n <li data-block-key=\"fe5cv\">UL List Item 1</li>\n <li data-block-key=\"6ort3\">UL List Item 2</li>\n </ul>\n <ol style=\"float: none; clear: both; list-style: decimal; margin-left: 2em; margin-bottom: 1em;\">\n <li data-block-key=\"d5s3r\">OL List Item 1</li>\n <li data-block-key=\"5l47j\">OL List Item 2</li>\n </ol>\n <img alt=\"IMG_4511\" class=\"richtext-image right\" height=\"375\" src=\"/media/images/IMG_4511.width-500.jpg\" style=\"float: right; margin-left: 1rem; margin-right: 0; margin-bottom: 1rem; height: auto;\" width=\"500\">\n <div style=\"clear: both;\"></div>\n</div>\n```\n\n## Configuration\n\nYou need to add one or both of these settings to your apps settings.\n\n- `F_RICHTEXT_FRAMEWORK_CONFIG`\n- `F_RICHTEXT_INLINE_CONFIG`\n\n### Example for adding classes to HTML tags\n\n```python\nF_RICHTEXT_FRAMEWORK_CONFIG = {\n # target html tags\n \"classes\": {\n \"h1\": \"heading-1\",\n \"h2\": \"heading-2\",\n \"ul\": \"list list--ul\",\n \"ol\": \"list list--ol\",\n \"a\": \"color-contrast-higher\",\n \"b\": \"font-bold\",\n \"i\": \"font-italic\",\n },\n # wrap the richtext content with a class\n \"wrapper_classes\": [\n \"text-component\",\n ],\n # swap the richtext image alignment classes\n \"alignment_classes\": {\n \"richtext-image left\": \"f-richtext-image f-richtext-image--left\",\n \"richtext-image right\": \"f-richtext-image f-richtext-image--right\",\n \"richtext-image full-width\": \"margin: 1em 0; width: 100%; height: auto;\",\n },\n # remove any empty HTML tags (blank lines in the richtext editor)\n \"remove_empty_tags\": [\n \"p\",\n ],\n # add a clearfix to the end of the content\n \"append_clearfix\": True,\n}\n```\n\n### Example for adding inline styles\n\n```python\nF_RICHTEXT_INLINE_CONFIG = {\n # target html tags\n \"styles\": {\n \"h1\": \"margin-bottom: 1em;\",\n \"h2\": \"margin-bottom: 1em;\",\n \"h3\": \"margin-bottom: 1em;\",\n \"h4\": \"margin-bottom: 1em;\",\n \"h5\": \"margin-bottom: 1em;\",\n \"h6\": \"margin-bottom: 1em;\",\n \"p\": \"margin-bottom: 1em;\",\n \"ul\": \"float: none; clear: both; list-style: disc; margin-left: 2em; margin-bottom: 1em;\",\n \"ol\": \"float: none; clear: both; list-style: decimal; margin-left: 2em; margin-bottom: 1em;\",\n \"code\": \"font-family: monospace; background-color: #f5f5f5; padding: 0.25rem 0.5rem;\",\n \"sub\": \"vertical-align: sub; font-size: smaller;\",\n \"sup\": \"vertical-align: super; font-size: smaller;\",\n \"div\": \"float: none; clear: both;\",\n \"iframe\": \"max-width: 100%; width: 720px; height: 400px; margin-top: 1em; margin-bottom: 1em;\",\n \"b\": \"font-weight: bold;\",\n \"i\": \"font-style: italic;\",\n },\n # wrap the richtext content with a style\n \"wrapper_styles\": [\n \"overflow:hidden;\",\n ],\n # swap the richtext image alignment classes for an inline style\n \"alignment_styles\": {\n \"richtext-image left\": \"float: left; margin-right: 1rem; margin-left: 0; margin-bottom: 1rem; height: auto;\",\n \"richtext-image right\": \"float: right; margin-left: 1rem; margin-right: 0; margin-bottom: 1rem; height: auto;\",\n \"richtext-image full-width\": \"margin: 1em 0; width: 100%; height: auto;\",\n },\n # remove any empty HTML tags (blank lines in the richtext editor)\n \"remove_empty_tags\": [\n \"p\",\n ],\n # add a clearfix to the end of the content\n \"append_clearfix\": True,\n}\n```\n\n## Optional usage\n\n### Use your own parser class\n\nThe parser class can be extended to add your own parsing requirements.\n\nCreate your own class that inherits from [fRichTextParser](./wagtail_f_richtext/parser.py) and add the following to your apps settings.\n\n```python\nF_RICHTEXT_PARSER_CLASS=\"the.dotted.path.to.your.own.Class\"\n```\n\n### Use your own runner function\n\nThe order of the parsing and loading of your configuration is done in the runner method that is called by the `f_richtext` filter.\n\nCreate your own [runner function](./wagtail_f_richtext/parser.py#L102) in a suitable place and add the following settings to your app.\n\n```python\nF_RICHTEXT_PARSER_RUNNER=\"the.dotted.path.to.your.own.function\"\n```\n\n## Contributing\n\nThe test app can be run to develop your contribution.\n\n1. Fork the repo and clone it to your computer.\n2. Change to the folder where you cloned it to.\n\nCreate a virtual environment and install the dependencies:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -e \".[development,testing]\"\n\n# run the migrations, add an admin account and start the app\npython manage.py migrate\npython manage.py createsuperuser\npython manage.py runserver\n```\n\nThen you can view the app at <http://localhost:8000> and login to the admin at <http://localhost:8000/admin>\n\nRun the tests:\n\n```bash\npython manage.py test\n```\n\nYou can use shortcuts in the [Makefile](./Makefile) to run the above commands.\n\n```bash\nmake setup\n```\n\nwill run all the above initial commands and creates a superuser with login credentials Username: `admin` Password: `admin`\n\n## Supports\n\n- Wagtail 4.1, 4.2, 5.0, 5.1. 5.2, 6.0\n- Django 3.2, 4.0, 4.1, 4.2\n- Python 3.8, 3.9, 3.10, 3.11, 3.12\n",
"bugtrack_url": null,
"license": " MIT License Copyright (c) 2022, Nick Moreton Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "An alternative Wagtail richtext filter that applies classes or styles to rich text HTML content.",
"version": "1.1.0",
"project_urls": {
"Changelog": "https://github.com/wagtail-packages/wagtail-f-richtext/blob/release/CHANGELOG.md",
"Issues": "https://github.com/wagtail-packages/wagtail-f-richtext/issues",
"Repository": "https://github.com/wagtail-packages/wagtail-f-richtext"
},
"split_keywords": [
"wagtail",
" richtext",
" filter",
" html",
" class",
" style"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2485ef32cd82de13e5bc6be6b1505b1265c34f978c9ff737523213e064f2ecf",
"md5": "29cf63f3881e367c2867830a7aca0a82",
"sha256": "a6f4dc5c534d9fb2ad47c457205b3f14bd4edc568d9bfcd4d8056582893d7a64"
},
"downloads": -1,
"filename": "wagtail_f_richtext-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29cf63f3881e367c2867830a7aca0a82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8716,
"upload_time": "2024-07-14T20:29:38",
"upload_time_iso_8601": "2024-07-14T20:29:38.726463Z",
"url": "https://files.pythonhosted.org/packages/a2/48/5ef32cd82de13e5bc6be6b1505b1265c34f978c9ff737523213e064f2ecf/wagtail_f_richtext-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "57ab1b29c7a462c9bf33a8e2c250691439d32c82f9d51d94e14e3914f91b9f73",
"md5": "4b5c51df091348e52f3919b32293a231",
"sha256": "249594e4527080f2eef3fb51f64d4e1bfc0bf2b51d01ab137c6e01b5a3a47d85"
},
"downloads": -1,
"filename": "wagtail_f_richtext-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4b5c51df091348e52f3919b32293a231",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13253,
"upload_time": "2024-07-14T20:29:40",
"upload_time_iso_8601": "2024-07-14T20:29:40.457234Z",
"url": "https://files.pythonhosted.org/packages/57/ab/1b29c7a462c9bf33a8e2c250691439d32c82f9d51d94e14e3914f91b9f73/wagtail_f_richtext-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-14 20:29:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wagtail-packages",
"github_project": "wagtail-f-richtext",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "wagtail-f-richtext"
}
