Custom Widget — subclass BaseWidget, register, ship

Walkthrough

1. 1

   Subclass BaseWidget — getName, getIcon, build this.block

   BaseWidget exposes three override hooks: getName() (palette label, REQUIRED — no default), getIcon() (Material Symbol Rounded name, defaults to 'extension'), and the constructor where you build the this.block shape that drops onto the canvas.

   this.block = new BlockElement('Block') is auto-created by the parent constructor — your constructor calls super() first, then appends child elements via this.block.appendElements([heading, paragraph, ...]). The block + child elements use the engine's standard Element classes (HeadingElement, PElement, ImageElement, etc.) so every standard format / inline-edit / drag-drop hook just works.

   Engine globals exposed by dist/builder.js: BaseWidget · BlockElement · HeadingElement · PElement · ImageElement · ButtonElement · plus the full element catalogue (see docs/core/ELEMENT_DEFINITION.md).

   JavaScript Copy

   class CalloutWidget extends BaseWidget {
     // Palette label — REQUIRED (no default).
     getName() { return 'Callout'; }
   
     // Material Symbol Rounded name. Defaults to 'extension'.
     getIcon() { return 'campaign'; }
   
     constructor() {
       super();  // creates this.block = new BlockElement('Block')
   
       // Build the shape the widget drops onto the canvas: a Heading +
       // a Paragraph nested inside the block.
       const heading   = new HeadingElement('Heading', 'h2', '✨ Pro tip');
       const paragraph = new PElement('Paragraph',
         'Drop this into any layout to highlight a key insight.'
       );
       this.block.appendElements([heading, paragraph]);
     }
   }

2. 2

   Register via widgetsBox.addWidget + render

   builder.widgetsBox is the live palette manager. addWidget(instance, options) registers a widget; options.group places it under a named heading in the palette ("Custom" / "Layout" / "Marketing" — anything you want). Multiple custom widgets share the same group string.

   After all widgets are registered, call widgetsBox.render() ONCE to paint the palette. Calling render mid-load() is wasteful — the engine's load() already paints once when the palette mount completes; tucking addWidget() calls into the load callback (or right after load resolves) means a single render covers all your customizations.

   The widget instance you register IS the palette item (it owns the palette DOM through render()). On drop, the engine clones the underlying block via renderBlock() (BaseWidget default: BlockElement.parse(this.block.getData())) — so dropping the same widget multiple times produces independent copies.

   JavaScript Copy

   // Mount + load the engine first; widgets register AFTER load() so the
   // palette mount is ready to receive them.
   const builder = new Builder({
     mainContainer:     '#MainContainer',
     widgetsContainer:  '#WidgetsContainer',
     settingsContainer: '#SettingsContainer',
   });
   
   builder.load(THEME_JSON, THEME_TEMPLATES, THEME_CONFIG_DATA, MEDIA_URL, () => {
     // Register inside the load callback — guarantees widgetsBox exists.
     builder.widgetsBox.addWidget(new CalloutWidget(), { group: 'Custom' });
     // Add more custom widgets in the same group:
     // builder.widgetsBox.addWidget(new TestimonialWidget(), { group: 'Custom' });
     // builder.widgetsBox.addWidget(new HeroBannerWidget(),  { group: 'Custom' });
   
     // ONE render() pass paints all custom widgets at once.
     builder.widgetsBox.render();
   });

3. 3

   Drag from palette → drop on canvas → inline-edit

   Once registered + rendered, the widget drags exactly like a stock widget. Drop targets are any droppable container (PageElement, BlockElement's child slots, GridElement's cells). The engine handles the drag-drop overlay, drop-zone visualisers, container highlight, and post-drop selection out of the box.

   The dropped block + child elements are LIVE Element instances — heading text is inline-editable on click, paragraph text is inline-editable, the block has its own background / padding settings panel, every nested element gets its own settings panel when selected. No additional wiring needed.

   To distinguish your widget's palette item in the DOM (for spec / styling): the engine adds widget-class="" to the palette item's root div. Your stylesheet can target [widget-class="CalloutWidget"] .widget-icon-box { background: var(--brand-accent); } for per-widget polish.

   JavaScript Copy

   // Custom CSS to style your widget in the palette (optional).
   // The engine writes widget-class="<ClassName>" on each palette item's
   // root div, giving you a stable hook for per-widget styling.
   
   // In your stylesheet:
   // [widget-class="CalloutWidget"] .widget-icon-box {
   //   background: rgba(245, 158, 11, 0.12);
   //   color: #d97706;
   // }
   
   // Buyer-side composition — register multiple widgets up-front,
   // each in their own group for natural palette organization.
   builder.widgetsBox.addWidget(new CalloutWidget(),     { group: 'Custom' });
   builder.widgetsBox.addWidget(new HeroBannerWidget(),  { group: 'Custom' });
   builder.widgetsBox.addWidget(new TestimonialWidget(), { group: 'Marketing' });
   builder.widgetsBox.addWidget(new PricingTableWidget(),{ group: 'Marketing' });
   builder.widgetsBox.render();  // ONE render covers all four.