django-prose-editor

StyleLoom uses contexts to determine which styling dialogs to show based on the user's position in the document.

Context Resolution Logic

When a user clicks a StyleLoom button, the extension walks up the ancestor tree from the cursor to find the deepest node whose type matches the context's types list.

• Catch-all Contexts: If a context has no types defined, it acts as a catch-all for any types not claimed by other specific contexts.
• Text Styles: Properties with the type "textStyle" are only included if the current selection is non-empty and is not a NodeSelection (i.e., it is a text selection).
• Node Selection: If a NodeSelection is active (e.g., selecting a whole table via its handle), the selected node itself is checked before walking up the ancestors.

Why use multiple contexts?

Because StyleLoom walks up the tree and stops at the first match, a single context targeting multiple types (e.g., ["table", "tableCell"]) would stop at the deepest match (the cell), making the parent properties (the table) unreachable. By defining separate contexts for table and tableCell, both buttons can be visible simultaneously when the cursor is inside a cell, allowing the user to style both the cell and the table independently.

The Menu extension allows you to organize UI elements into groups. You can integrate your extension by implementing the addMenuItems method, which is called during editor initialization. This method provides access to the editor instance, a buttons helper, and the menu object.

Menu Item Properties

When calling menu.defineItem({...}), you can use the following properties:

• name: Unique identifier for the menu item.
• groups: A space-separated list of groups this item belongs to.
• priority: (Optional) Higher priorities are sorted first.
• command: A function (editor) => void that performs an action.
• button: The DOM element representing the menu button.
• option: (Optional) Element when shown in a dropdown.
• enabled: (Optional) Function returning a boolean indicating if the item is clickable.
• active: (Optional) Function returning a boolean indicating if the item should appear active.
• hidden: (Optional) Function returning a boolean indicating if the item should be hidden.
• update: (Optional) Function to update dynamic content in the menu item.

export const MyExtension = SomeBaseExtension.extend({
  addMenuItems({ editor, buttons, menu }) {
    // Register menu items for this extension using the new menu API
    menu.defineItem({
      name: "myExtension",
      groups: "myExtension",
      command: (editor) => editor.chain().myCommand().focus().run(),
      button: buttons.material("icon_name", "tooltip text"),
      enabled: (editor) => true,
      active: (editor) => editor.isActive("myExtension")
    })
  },
})

To use ClassLoom in a Django model field, include it in the extensions dictionary of a ProseEditorField. You must define a groups object where each key represents a menu group.

To make the ClassLoom buttons visible in the editor UI, you must also integrate them into the Menu extension configuration by referencing them with the prefix classLoom:<key>.

Note on Menu Integration: Each group produces a dropdown named classLoom:<key>. Add these to your Menu configuration to display the buttons. Each dropdown includes a default entry to clear all classes in that group, plus an entry for each defined class.

content = ProseEditorField(
    extensions={
        "Bold": True,
        "Italic": True,
        "Table": True,
        "ClassLoom": {
            "groups": {
                "tableStyles": {
                    "title": "Table style",
                    "type": "table",
                    "classes": [
                        {"className": "table--bordered", "title": "Bordered"},
                        {"className": "table--striped",  "title": "Striped"},
                    ],
                },
                "emphasisStyles": {
                    "title": "Emphasis style",
                    "type": "italic",
                    "classes": ["theme-color", "grey-color"],
                },
                "textDecoration": {
                    "title": "Text decoration",
                    "type": "text",
                    "combinable": True,
                    "classes": [
                        {"className": "color--primary",      "title": "Primary colour"},
                        {"className": "underline--dashed",   "title": "Dashed underline"},
                    ],
                },
            },
        },
        "Menu": {
            "groups": [
                {"group": "blockType -lists", "type": "dropdown", "minItems": 2},
                {"group": "lists"},
                {"group": "nodes -blockType -lists"},
                {"group": "marks"},
                {"group": "classLoom:emphasisStyles", "type": "dropdown"},
                {"group": "classLoom:textDecoration", "type": "dropdown"},
                {"group": "link"},
                {"group": "table"},
                {"group": "classLoom:tableStyles", "type": "dropdown"},
                {"group": "history"},
                {"group": "utility"},
            ],
        },
    },
)