dj-editor-js 0.1.0__py3-none-any.whl

dj_editor_js-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: dj-editor-js
+Version: 0.1.0
+Summary: A Django library to integrate the Editor.js editor with image handling and custom tools.
+Author-email: Otto <opensource@otto.srl>
+License: MIT License
+        
+        Copyright (c) 2025 Otto.srl
+        
+        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.
+Project-URL: Homepage, https://github.com/otto-torino/django-editor-js
+Project-URL: Repository, https://github.com/otto-torino/django-editor-js
+Project-URL: Bug Tracker, https://github.com/otto-torino/django-editor-js/issues
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Dynamic: license-file
+
+# Django Editor.js
+
+[![PyPI version](https://badge.fury.io/py/django-editor-js.svg)](https://badge.fury.io/py/django-editor-js)
+[![Build Status](https://github.com/otto-torino/django-editor-js/actions/workflows/ci.yml/badge.svg)](https://github.com/otto-torino/django-editor-js/actions/workflows/ci.yml)
+[![Coverage Status](https://codecov.io/gh/otto-torino/django-editor-js/graph/badge.svg)](https://codecov.io/gh/otto-torino/django-editor-js)
+
+A modern, extensible, and self-contained Django app for integrating the block-style [Editor.js](https://editorjs.io/) into your projects.
+
+This library provides a custom `EditorJSField` for your models and a sandboxed iframe widget for the Django admin, ensuring a clean, conflict-free editing experience. It comes with powerful features like automatic image management, dynamic tool configuration, and a customizable HTML renderer.
+
+## Key Features
+
+-   **Iframe Sandboxing**: The editor is rendered within an `iframe` to prevent CSS and JavaScript conflicts with the Django admin or your site's styles.
+-   **Dynamic Tool Configuration**: Configure all Editor.js tools directly from your project's `settings.py`. Add, remove, or override the default toolset, including your own custom-built plugins.
+-   **Automatic Image Management**: Integrated image upload endpoint with configurable storage. Automatically deletes unused images from storage when a model instance is updated or deleted.
+-   **Extensible HTML Renderer**: A server-side Python class converts the saved JSON data into clean HTML, with methods for each block type that can be easily extended or overridden.
+-   **Built-in Template Filter**: Render your content with a simple `{% load ... %}` and filter call, no need to write your own rendering logic.
+-   **Sensible Defaults**: Works out-of-the-box with a rich set of common Editor.js tools.
+-   **Admin-Friendly UI**: Features include automatic iframe resizing and a fullscreen editing mode for a better user experience.
+
+---
+
+## Installation
+
+1.  Install the package from PyPI:
+    ```bash
+    pip install django-editor-js
+    ```
+
+2.  Add `'editor_js'` to your `INSTALLED_APPS` in `settings.py`:
+    ```python
+    # settings.py
+    INSTALLED_APPS = [
+        # ...
+        'django.contrib.admin',
+        'django.contrib.auth',
+        # ...
+        'editor_js',
+    ]
+    ```
+
+---
+
+## Configuration
+
+1.  **Include the URLs**: Add the library's URLs to your project's `urls.py`. These are required for the iframe and the image upload endpoint.
+
+    ```python
+    # your_project/urls.py
+    from django.urls import path, include
+    
+    urlpatterns = [
+        path('admin/', admin.site.urls),
+        path('editor-js/', include('editor_js.urls')),
+        # ... your other urls
+    ]
+    ```
+
+2.  **Configure Settings (Optional)**: You can customize the library by adding an `EDITOR_JS` dictionary to your `settings.py`. If you don't provide this, the library will use its sensible defaults.
+
+    ```python
+    # settings.py
+    EDITOR_JS = {
+        # Define a custom storage backend for uploaded images.
+        "STORAGE_BACKEND": "app.storage.PrivateMediaStorage",
+    
+        # Specify the custom CSS files to be loaded inside the editor's iframe.
+        "CSS_FILES": ["my_app/css/style.css", "other_app/css/style.css"],
+    
+        # Specify a custom Python class to render the JSON data to HTML.
+        "RENDERER_CLASS": "my_app.renderers.MyCustomRenderer",
+    
+        # Configure the tools available to the editor.
+        "TOOLS": {
+            # Add a new custom tool
+            'my_custom_tool': {
+                'class': 'MyCustomTool',
+                'script': 'my_app/js/my-custom-tool.js',
+                'static': True, # True if the script is a local static file
+                'config': {
+                    'placeholder': 'Enter your custom text...'
+                }
+            },
+            # Remove a default tool
+            'quote': None,
+        }
+    }
+    ```
+
+---
+
+## Usage
+
+### In Your Models
+
+Use the `EditorJSField` in your models as you would any other Django model field. It stores the editor's content as JSON.
+
+- **To use a custom set of Editor.js tools for a field**, pass a `tools` dictionary to the field.
+- **To use the global (default) tool configuration**, define the field without the `tools` argument.
+
+Since EditorJSField inherits from Django's models.JSONField, you can also pass any of its standard attributes, such as `blank=True` or `null=True`.
+
+Example:
+```python
+# my_app/models.py
+from django.db import models
+from editor_js.fields import EditorJSField
+
+class Post(models.Model):
+    title = models.CharField(max_length=200)
+
+    # This field will only have Header and List tools
+    summary = EditorJSField(tools={
+        'header': {
+            'class': 'Header',
+            'script': 'https://cdn.jsdelivr.net/npm/@editorjs/header@latest',
+        },
+        'list': {
+            'class': 'EditorjsList',
+            'script': 'https://cdn.jsdelivr.net/npm/@editorjs/list@latest',
+        }
+    })
+
+    # This field will use the default or global tool configuration
+    body = EditorJSField()
+    # ...
+```
+
+The field will automatically render the iframe widget in the Django admin.
+
+### Rendering Content in Templates
+
+The library includes a built-in template filter to easily render your `EditorJSField` data as HTML.
+
+1.  **Load the filter** in your template:
+    ```django
+    {% load editor_js_filters %}
+    ```
+
+2.  **Apply the filter** to your field's data:
+    ```django
+    <!-- post_detail.html -->
+    {% load editor_js_filters %}
+    
+    <article>
+        <h1>{{ post.title }}</h1>
+        <div class="content">
+            {{ post.body|render_editor_js }}
+        </div>
+    </article>
+    ```
+
+The filter will automatically use your custom renderer class if you have specified one in your settings.
+
+---
+
+## Demo Application
+
+A fully functional demo application is included to showcase the features of this library. To try it out:
+
+**1. Clone the repository:**
+```bash
+git clone https://github.com/otto-torino/django-editor-js.git
+cd django-editor-js
+```
+
+**2. Run the demo:**
+
+- **On Windows:**
+    ```cmd
+    run_demo.bat
+    ```
+
+- **On macOS / Linux:**
+    ```bash
+    ./run_demo.sh
+    ```
+
+This will set up a minimal Django project, create a database, and start the development server so you can explore the editor in action.
+
+---
+
+## Customization
+
+This library is designed to be highly extensible.
+
+### Adding & Removing Tools
+
+You can fully control the tools available in the editor via the `EDITOR_JS['TOOLS']` dictionary in `settings.py`.
+
+-   **To remove a default tool**, set its key to `None`:
+    ```python
+    "TOOLS": { 'raw': None, 'table': None }
+    ```
+
+-   **To add a new tool**, add a new key with its configuration:
+    ```python
+    "TOOLS": {
+        'my_checklist': {
+            'class': 'Checklist', # The JS class name
+            'script': '[https://cdn.jsdelivr.net/npm/@editorjs/checklist@latest](https://cdn.jsdelivr.net/npm/@editorjs/checklist@latest)', # URL or static path
+            'static': False, # Is it a local static file?
+        }
+    }
+    ```
+
+The library comes with the following default tools: **Header**, **List**, **Quote**, **Table**, **Raw HTML**, **Embed**, **Image**, **Button**, and **Divider**.
+
+### Custom HTML Rendering
+
+If you add a custom tool, you'll need to tell Django how to render it.
+
+1.  Subclass the provided `EditorJsRenderer` and add a `render_my_tool_name` method.
+2.  Update `settings.py` to point to your new class.
+
+```python
+# my_app/renderers.py
+from editor_js.renderers import EditorJsRenderer
+
+class MyCustomRenderer(EditorJsRenderer):
+    def render_my_custom_tool(self, data):
+        # Logic to convert the tool's data to HTML
+        items = data.get('items', [])
+        html = "<ul>"
+        for item in items:
+            checked = 'checked' if item.get('checked') else ''
+            text = self.escape(item.get('text', ''))
+            html += f'<li><input type="checkbox" {checked} disabled> {text}</li>'
+        html += "</ul>"
+        return html
+
+# settings.py
+EDITOR_JS = {
+    "RENDERER_CLASS": "my_app.renderers.MyCustomRenderer",
+    # ...
+}
+```
+
+### Custom Storage & Styling
+
+-   **Storage**: To use a different storage system (like Amazon S3), set the `STORAGE_BACKEND` setting to the dotted path of your storage class (e.g., `'storages.backends.s3boto3.S3Boto3Storage'`).
+-   **Styling**: To match the editor's appearance with your frontend, provide a path to a custom CSS file in the `CSS_FILE` setting. This file will be loaded inside the editor's iframe.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

dj_editor_js-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+dj_editor_js-0.1.0.dist-info/licenses/LICENSE,sha256=p3TV7N6F4YWrorog8C8yRS8rZcjYHuiILyAykwwUeiQ,1064
+editor_js/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+editor_js/apps.py,sha256=-ezh8p5NmTSpvR9DLhbt2pYf8kckEjyYCDUdXNajHXo,149
+editor_js/config.py,sha256=rv6mS8zb4YcQiJg9ui9mgZG1WTqqZkmV-t13MxHXqDk,2535
+editor_js/fields.py,sha256=HRdT2CzNEh9yElm02efKxgN3yvfNQ78U4U8QW6we37Q,4653
+editor_js/models.py,sha256=Vjc0p2XbAPgE6HyTF6vll98A4eDhA5AvaQqsc4kQ9AQ,57
+editor_js/renderers.py,sha256=D2_bZUC7NFscbvoHvqGqjmhFxRhn6yb98dJxYCzKse4,4996
+editor_js/urls.py,sha256=pkZQWZmfbytNATmKEEY8ma0BStWQsGVuIrQvOqoCscU,256
+editor_js/views.py,sha256=BhZvOh58yDV-_fOBwDk6cxGSi-Geb1-0C-OM2jAY2PU,1787
+editor_js/widgets.py,sha256=eBXBljAumOXb1BndeHOWWSOD7w0FLAqI0mmXFk0Yze4,705
+editor_js/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+editor_js/static/editor_js/css/editor_js_admin.css,sha256=2TzyeMeKQTcqhMgYPY4c2DovcwKFNRRjg2S9yJND7NM,5310
+editor_js/static/editor_js/js/editor_js_iframe.js,sha256=jG6iCYPROiGUwfH7lCM6lrmtoj_XU3rmSeZa_r0Nbn8,5769
+editor_js/static/editor_js/js/editor_js_widget.js,sha256=lPP9CXg9tKT2T9tk72aio4WIwVKfAmq0EM6DMlx8utA,4588
+editor_js/static/editor_js/js/plugins/button-tool.js,sha256=9_cftdTZCo0XJqmH8F7iKltN0aOFWUvnlvwbqtuzyHo,7473
+editor_js/static/editor_js/js/plugins/divider-tool.js,sha256=fmPv-Khr1zBTokvPz5FNFTscs-6C6Y3ksjWpKHF3Ik4,440
+editor_js/templates/editor_js/editor_js_iframe.html,sha256=7U9CnGzvndDgvcn3TC_2acYpA3x-JXtV2-6980CxhMM,1337
+editor_js/templates/editor_js/admin/widgets/editor_js_widget.html,sha256=Z6oTHUncX2qME_zffVO97L6A_7rZzuEMCcAqhpHSz_c,1659
+editor_js/templatetags/editor_js_filters.py,sha256=ZDuw2JnRwqLVwFwsSyPQ8afr4a7f-gsOLt7PEKb5oy4,998
+dj_editor_js-0.1.0.dist-info/METADATA,sha256=_tpnxzUrw3fuPyWJm4Di76s8MF2gvbiP9jYXNwuZepg,11098
+dj_editor_js-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dj_editor_js-0.1.0.dist-info/top_level.txt,sha256=abe_r8WCX3gATlqhMA6jUtD3TDkypZYcPntRMxifJ4M,10
+dj_editor_js-0.1.0.dist-info/RECORD,,

dj_editor_js-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dj_editor_js-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Otto.srl
+
+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.

dj_editor_js-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+editor_js

editor_js/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class EditorJsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'editor_js'

editor_js/config.py

@@ -0,0 +1,89 @@
+from django.conf import settings
+from django.core.files.storage import default_storage
+from django.utils.module_loading import import_string
+
+DEFAULT_EDITOR_JS_TOOLS = {
+    'header': {
+        'class': 'Header',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/header@latest',
+    },
+    'list': {
+        'class': 'EditorjsList',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/list@latest',
+    },
+    'quote': {
+        'class': 'Quote',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/quote@latest',
+    },
+    'table': {
+        'class': 'Table',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/table@latest',
+        'config': {
+            'inlineToolbar': True,
+        }
+    },
+    'raw': {
+        'class': 'RawTool',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/raw@latest',
+    },
+    'embed': {
+        'class': 'Embed',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/embed@latest',
+        'config': {
+            'inlineToolbar': True,
+        }
+    },
+    'image': {
+        'class': 'ImageTool',
+        'script': 'https://cdn.jsdelivr.net/npm/@editorjs/image@latest',
+    },
+    'button': {
+        'class': 'ButtonTool',
+        'script': 'editor_js/js/plugins/button-tool.js',
+        'static': True,
+    },
+    'divider': {
+        'class': 'DividerTool',
+        'script': 'editor_js/js/plugins/divider-tool.js',
+        'static': True,
+    }
+}
+
+def get_editor_js_config():
+    """
+    Returns the final configuration for Editor.js, merging the library defaults
+    with the user's custom settings.
+    """
+    config = {
+        'STORAGE_BACKEND': None,
+        'CSS_FILES': ['editor_js/css/editor_js_admin.css',],
+        'RENDERER_CLASS': 'editor_js.renderers.EditorJsRenderer',
+        'TOOLS': DEFAULT_EDITOR_JS_TOOLS
+    }
+
+    user_settings = getattr(settings, 'EDITOR_JS', {})
+
+    if 'TOOLS' in user_settings:
+        merged_tools = config['TOOLS'].copy()
+        merged_tools.update(user_settings['TOOLS'])
+        user_settings['TOOLS'] = merged_tools
+
+    config.update(user_settings)
+    
+    return config
+
+def get_editor_js_storage():
+    """
+    Helper function to get the storage class.
+    Uses the class specified in settings.EDITOR_JS,
+    otherwise falls back to default_storage.
+    """
+    config = get_editor_js_config()
+    storage_path = config.get('STORAGE_BACKEND')
+
+    if storage_path:
+        try:
+            return import_string(storage_path)()
+        except ImportError:
+            pass
+    return default_storage

editor_js/fields.py

@@ -0,0 +1,125 @@
+from django.db import models
+from django.db.models.signals import post_delete
+from urllib.parse import unquote
+
+from .widgets import EditorJsIframeWidget
+from .config import get_editor_js_storage
+
+
+def _delete_editor_js_images_on_delete(sender, instance, **kwargs):
+    """
+    Deletes all images used in all EditorJS fields of the given instance.
+
+    This function is meant to be used as a post_delete signal handler.
+    """
+    for field in sender._meta.get_fields():
+        if isinstance(field, EditorJSField):
+            data = getattr(instance, field.attname, None)
+            if not data:
+                continue
+
+            urls_to_delete = field._extract_image_urls(data)
+            storage = get_editor_js_storage()
+            base_url = getattr(storage, "base_url", None)
+
+            if not base_url:
+                continue
+
+            for url in urls_to_delete:
+                if url.startswith(base_url):
+                    relative_path = url.replace(base_url, "", 1).lstrip("/")
+                    decoded_path = unquote(relative_path)
+                    try:
+                        if storage.exists(decoded_path):
+                            storage.delete(decoded_path)
+                    except Exception as e:
+                        print(f"Error deleting file on instance delete: {e}")
+
+
+class EditorJSField(models.JSONField):
+    """
+    A JSONField that stores Editor.js data. It deletes the images used in the
+    Editor.js data when the instance is deleted.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """
+        :param tools: A dictionary with a specific tool configuration for this field,
+                      overriding the global settings.
+        """
+        self.tools = kwargs.pop("tools", None)
+        super().__init__(*args, **kwargs)
+
+    def formfield(self, **kwargs):
+        """
+        Return a form field for the Editor.js data.
+        """
+        config = {}
+        if self.tools:
+            config['tools'] = self.tools
+        
+        kwargs["widget"] = EditorJsIframeWidget(attrs={"config": config})
+        return super().formfield(**kwargs)
+
+    def contribute_to_class(self, cls, name, **kwargs):
+        """
+        Connect a post_delete signal to the model class to delete the images
+        used in the Editor.js data when the instance is deleted.
+        """
+        super().contribute_to_class(cls, name, **kwargs)
+        if not hasattr(cls, "_editor_js_delete_signal_connected"):
+            post_delete.connect(
+                _delete_editor_js_images_on_delete, sender=cls, weak=False
+            )
+            cls._editor_js_delete_signal_connected = True
+
+    def _extract_image_urls(self, data):
+        """
+        Extract the URLs of the images used in the Editor.js data.
+        """
+        image_urls = []
+        if not isinstance(data, dict) or "blocks" not in data:
+            return image_urls
+        for block in data.get("blocks", []):
+            if block.get("type") == "image":
+                file_data = block.get("data", {}).get("file", {})
+                url = file_data.get("url")
+                if url:
+                    image_urls.append(url)
+        return image_urls
+
+    def pre_save(self, model_instance, add):
+        """
+        Delete the images that are no longer used in the Editor.js data when
+        the instance is saved.
+        """
+        new_value = super().pre_save(model_instance, add)
+        old_value = None
+        if model_instance.pk:
+            try:
+                old_instance = model_instance.__class__.objects.get(
+                    pk=model_instance.pk
+                )
+                old_value = getattr(old_instance, self.attname)
+            except model_instance.__class__.DoesNotExist:
+                pass
+
+        old_image_urls = set(self._extract_image_urls(old_value))
+        new_image_urls = set(self._extract_image_urls(new_value))
+        urls_to_delete = old_image_urls - new_image_urls
+
+        if urls_to_delete:
+            storage = get_editor_js_storage()
+            base_url = getattr(storage, "base_url", None)
+
+            if base_url:
+                for url in urls_to_delete:
+                    if url.startswith(base_url):
+                        relative_path = url.replace(base_url, "", 1).lstrip("/")
+                        decoded_path = unquote(relative_path)
+                        try:
+                            if storage.exists(decoded_path):
+                                storage.delete(decoded_path)
+                        except Exception as e:
+                            print(f"Error deleting orphaned file: {e}")
+        return new_value

editor_js/models.py

@@ -0,0 +1,3 @@
+from django.db import models
+
+# Create your models here.