wagtail_editorjs
================
*Check out [Awesome Wagtail](https://github.com/springload/awesome-wagtail) for more awesome packages and resources from the Wagtail community.*
A Wagtail EditorJS widget with page/image chooser support, document support and more!
## Add features:
* [Add an EditorJS feature](https://github.com/Nigel2392/wagtail_editorjs/blob/main/docs/editorjs_feature.md "Simple Image Feature")
* [Add an EditorJS tune](https://github.com/Nigel2392/wagtail_editorjs/blob/main/docs/tunes.md "text-alignment-tune") (Already exists in `wagtail_editorjs`, just an example.)
Quick start
-----------
1. Add 'wagtail_editorjs' to your INSTALLED_APPS setting like this:
```
INSTALLED_APPS = [
...,
'wagtail_editorjs',
]
```
2. Add the HTML to your template:
```django-html
<link rel="stylesheet" href="{% static 'wagtail_editorjs/css/frontend.css' %}">
{% load editorjs %}
{# CSS files for features #}
{% editorjs_static "css" %}
{% editorjs self.editor_field %}
{# JS files for features #}
{% editorjs_static "js" %}
```
3. Add the field to your model:
```python
...
from wagtail_editorjs.fields import EditorJSField
from wagtail_editorjs.blocks import EditorJSBlock
class HomePage(Page):
content_panels = [
FieldPanel("editor_field"),
FieldPanel("content"),
]
editor_field = EditorJSField(
# All supported features
features=[
'attaches',
'background-color-tune',
'button',
'checklist',
'code',
'delimiter',
'document',
'drag-drop',
'header',
'image',
'images',
'inline-code',
'link',
'link-autocomplete',
'marker',
'nested-list',
'paragraph',
'quote',
'raw',
'table',
'text-alignment-tune',
'text-color-tune',
'text-variant-tune',
'tooltip',
'underline',
'undo-redo',
'warning'
],
blank=True,
null=True,
)
# Or as a block
content = fields.StreamField([
('editorjs', EditorJSBlock(features=[
# ... same as before
])),
], blank=True, use_json_field=True)
```
## List features
This readme might not fully reflect which features are available.
To find this out - you can:
1. start the python shell
```bash
py ./manage.py shell
```
2. Print all the available features:
```python
from wagtail_editorjs.registry import EDITOR_JS_FEATURES
print(EDITOR_JS_FEATURES.keys())
dict_keys([... all registered features ...])
```
## Register a Wagtail block as a feature
It is also possible to register a Wagtail block as a feature.
It is important to note that the block must be a `StructBlock` or a subclass of `StructBlock`.
It is **not** allowed to be or include:
* A `StreamBlock` (mainly due to styling issues)
* A `ListBlock` (mainly due to styling issues)
* A `RichTextBlock` (cannot initialize)
*Help with these issues is highly appreciated!*
Example:
```python
from wagtail import hooks
from wagtail_editorjs.features import (
WagtailBlockFeature,
EditorJSFeatureStructBlock,
)
from wagtail_editorjs.registry import (
EditorJSFeatures,
)
from wagtail_editorjs.hooks import REGISTER_HOOK_NAME
from wagtail import blocks
class HeadingBlock(blocks.StructBlock):
title = blocks.CharBlock()
subtitle = blocks.CharBlock()
class TextBlock(EditorJSFeatureStructBlock):
heading = HeadingBlock()
body = blocks.TextBlock()
class Meta:
template = "myapp/text_block.html"
allowed_tags = ["h1", "h2", "p"]
# Html looks like:
# <h1>{{ self.heading.title }}</h1>
# <h2>{{ self.heading.subtitle }}</h2>
# <p>{{ self.body }}</p>
@hooks.register(REGISTER_HOOK_NAME)
def register_editor_js_features(registry: EditorJSFeatures):
registry.register(
"wagtail-text-block",
WagtailBlockFeature(
"wagtail-text-block",
block=TextBlock(),
),
)
```
The block will then be rendered as any structblock, but it will be wrapped in a div with the class `wagtail-text-block` (the feature name).
Example:
```html
<div class="wagtail-text-block">
<h1>My title</h1>
<h2>My subtitle</h2>
<p>My body</p>
</div>
```
## Settings
### `EDITORJS_CLEAN_HTML`
Default: `True`
Clean the HTML output on rendering.
This happens every time the field is rendered.
It might be smart to set up some sort of caching mechanism.
Optionally; cleaning can be FORCED by passing `clean=True` or `False` to the `render_editorjs_html` function.
### `EDITORJS_ADD_BLOCK_ID`
Default: `true`
Add a block ID to each editorJS block when rendering.
This is useful for targeting the block with JavaScript,
or possibly creating some link from frontend to admin area.
### `EDITORJS_BLOCK_ID_ATTR`
Default: `data-editorjs-block-id`
The attribute name to use for the block ID.
This is only used if `ADD_BLOCK_ID` is True.
### `EDITORJS_USE_FULL_URLS`
Default: `False`
Use full urls if the request is available in the EditorJS rendering context.
Raw data
{
"_id": null,
"home_page": "https://github.com/Nigel2392/wagtail_editorjs",
"name": "wagtail-editorjs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Nigel",
"author_email": "nigel@goodadvice.it",
"download_url": "https://files.pythonhosted.org/packages/f2/2d/d19c6de2af7c0b61979afe68b25d948c63a5fe7eadfcd4c6c7077e61f2ea/wagtail_editorjs-1.6.5.tar.gz",
"platform": null,
"description": "wagtail_editorjs\r\n================\r\n\r\n*Check out [Awesome Wagtail](https://github.com/springload/awesome-wagtail) for more awesome packages and resources from the Wagtail community.*\r\n\r\nA Wagtail EditorJS widget with page/image chooser support, document support and more!\r\n\r\n## Add features:\r\n\r\n* [Add an EditorJS feature](https://github.com/Nigel2392/wagtail_editorjs/blob/main/docs/editorjs_feature.md \"Simple Image Feature\")\r\n* [Add an EditorJS tune](https://github.com/Nigel2392/wagtail_editorjs/blob/main/docs/tunes.md \"text-alignment-tune\") (Already exists in `wagtail_editorjs`, just an example.)\r\n\r\nQuick start\r\n-----------\r\n\r\n1. Add 'wagtail_editorjs' to your INSTALLED_APPS setting like this:\r\n\r\n ```\r\n INSTALLED_APPS = [\r\n ...,\r\n 'wagtail_editorjs',\r\n ]\r\n ```\r\n2. Add the HTML to your template:\r\n\r\n ```django-html\r\n <link rel=\"stylesheet\" href=\"{% static 'wagtail_editorjs/css/frontend.css' %}\">\r\n {% load editorjs %}\r\n\r\n {# CSS files for features #}\r\n {% editorjs_static \"css\" %}\r\n\r\n {% editorjs self.editor_field %}\r\n\r\n {# JS files for features #}\r\n {% editorjs_static \"js\" %}\r\n ```\r\n3. Add the field to your model:\r\n\r\n ```python\r\n ...\r\n from wagtail_editorjs.fields import EditorJSField\r\n from wagtail_editorjs.blocks import EditorJSBlock\r\n\r\n\r\n class HomePage(Page):\r\n content_panels = [\r\n FieldPanel(\"editor_field\"),\r\n FieldPanel(\"content\"),\r\n ]\r\n editor_field = EditorJSField(\r\n # All supported features\r\n features=[\r\n 'attaches',\r\n 'background-color-tune',\r\n 'button',\r\n 'checklist',\r\n 'code',\r\n 'delimiter',\r\n 'document',\r\n 'drag-drop',\r\n 'header',\r\n 'image',\r\n 'images',\r\n 'inline-code',\r\n 'link',\r\n 'link-autocomplete',\r\n 'marker',\r\n 'nested-list',\r\n 'paragraph',\r\n 'quote',\r\n 'raw',\r\n 'table',\r\n 'text-alignment-tune',\r\n 'text-color-tune',\r\n 'text-variant-tune',\r\n 'tooltip',\r\n 'underline',\r\n 'undo-redo',\r\n 'warning'\r\n ],\r\n blank=True,\r\n null=True,\r\n )\r\n\r\n # Or as a block\r\n content = fields.StreamField([\r\n ('editorjs', EditorJSBlock(features=[\r\n # ... same as before\r\n ])),\r\n ], blank=True, use_json_field=True)\r\n ```\r\n\r\n## List features\r\n\r\nThis readme might not fully reflect which features are available.\r\n\r\nTo find this out - you can:\r\n\r\n1. start the python shell\r\n\r\n ```bash\r\n py ./manage.py shell\r\n ```\r\n2. Print all the available features:\r\n\r\n ```python\r\n from wagtail_editorjs.registry import EDITOR_JS_FEATURES\r\n print(EDITOR_JS_FEATURES.keys())\r\n dict_keys([... all registered features ...])\r\n ```\r\n\r\n## Register a Wagtail block as a feature\r\n\r\nIt is also possible to register a Wagtail block as a feature.\r\n\r\nIt is important to note that the block must be a `StructBlock` or a subclass of `StructBlock`.\r\n\r\nIt is **not** allowed to be or include:\r\n\r\n* A `StreamBlock` (mainly due to styling issues)\r\n* A `ListBlock` (mainly due to styling issues)\r\n* A `RichTextBlock` (cannot initialize)\r\n\r\n*Help with these issues is highly appreciated!*\r\n\r\nExample:\r\n\r\n```python\r\nfrom wagtail import hooks\r\nfrom wagtail_editorjs.features import (\r\n WagtailBlockFeature,\r\n EditorJSFeatureStructBlock,\r\n)\r\nfrom wagtail_editorjs.registry import (\r\n EditorJSFeatures,\r\n)\r\nfrom wagtail_editorjs.hooks import REGISTER_HOOK_NAME\r\n\r\nfrom wagtail import blocks\r\n\r\nclass HeadingBlock(blocks.StructBlock):\r\n title = blocks.CharBlock()\r\n subtitle = blocks.CharBlock()\r\n\r\nclass TextBlock(EditorJSFeatureStructBlock):\r\n heading = HeadingBlock()\r\n body = blocks.TextBlock()\r\n\r\n class Meta:\r\n template = \"myapp/text_block.html\"\r\n allowed_tags = [\"h1\", \"h2\", \"p\"]\r\n # Html looks like:\r\n # <h1>{{ self.heading.title }}</h1>\r\n # <h2>{{ self.heading.subtitle }}</h2>\r\n # <p>{{ self.body }}</p>\r\n\r\n@hooks.register(REGISTER_HOOK_NAME)\r\ndef register_editor_js_features(registry: EditorJSFeatures):\r\n\r\n registry.register(\r\n \"wagtail-text-block\",\r\n WagtailBlockFeature(\r\n \"wagtail-text-block\",\r\n block=TextBlock(),\r\n ),\r\n )\r\n```\r\n\r\nThe block will then be rendered as any structblock, but it will be wrapped in a div with the class `wagtail-text-block` (the feature name).\r\n\r\nExample:\r\n \r\n```html\r\n<div class=\"wagtail-text-block\">\r\n <h1>My title</h1>\r\n <h2>My subtitle</h2>\r\n <p>My body</p>\r\n</div>\r\n```\r\n\r\n## Settings\r\n\r\n### `EDITORJS_CLEAN_HTML`\r\n\r\nDefault: `True`\r\nClean the HTML output on rendering.\r\nThis happens every time the field is rendered.\r\nIt might be smart to set up some sort of caching mechanism.\r\nOptionally; cleaning can be FORCED by passing `clean=True` or `False` to the `render_editorjs_html` function.\r\n\r\n### `EDITORJS_ADD_BLOCK_ID`\r\n\r\nDefault: `true`\r\nAdd a block ID to each editorJS block when rendering.\r\nThis is useful for targeting the block with JavaScript,\r\nor possibly creating some link from frontend to admin area.\r\n\r\n### `EDITORJS_BLOCK_ID_ATTR`\r\n\r\nDefault: `data-editorjs-block-id`\r\nThe attribute name to use for the block ID.\r\nThis is only used if `ADD_BLOCK_ID` is True.\r\n\r\n### `EDITORJS_USE_FULL_URLS`\r\n\r\nDefault: `False`\r\nUse full urls if the request is available in the EditorJS rendering context.\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "EditorJS as a widget for Wagtail, with Page- and Image chooser support",
"version": "1.6.5",
"project_urls": {
"Homepage": "https://github.com/Nigel2392/wagtail_editorjs"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f22dd19c6de2af7c0b61979afe68b25d948c63a5fe7eadfcd4c6c7077e61f2ea",
"md5": "665dcb9eae6e7cd9b2477802f3857591",
"sha256": "1e21fee36bcb89a3656d3a1712434ebdffc7f514c6b8bc1200198ba6f187fb71"
},
"downloads": -1,
"filename": "wagtail_editorjs-1.6.5.tar.gz",
"has_sig": false,
"md5_digest": "665dcb9eae6e7cd9b2477802f3857591",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 240785,
"upload_time": "2024-05-14T20:48:01",
"upload_time_iso_8601": "2024-05-14T20:48:01.127805Z",
"url": "https://files.pythonhosted.org/packages/f2/2d/d19c6de2af7c0b61979afe68b25d948c63a5fe7eadfcd4c6c7077e61f2ea/wagtail_editorjs-1.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-14 20:48:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Nigel2392",
"github_project": "wagtail_editorjs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wagtail-editorjs"
}
JSON
