Skip to main content

Editor Elements

Editor Elements allow your app to extend the SitePack visual editor with custom blocks that merchants can drag and drop onto their pages. This provides a seamless way for merchants to use your app's functionality directly within their site's layout.

How Editor Elements Work​

  1. Registration: You define your custom blocks in the editor.blocks section of your app.json.
  2. Rendering: You provide a Twig template that SitePack uses to render the preview of your block within the editor canvas.
  3. Interaction: You can use the SitePackAdminSDK to add interactivity and custom settings to your blocks.

Registration (app.json)​

To register a custom block, add it to the editor section:

{
  "editor": {
    "preview_template": "templates/my_block_preview.html.twig",
    "blocks": [
      {
        "id": "my-custom-element",
        "label": "My Custom Element",
        "icon": "star"
      }
    ],
    "assets": {
      "js": ["assets/editor.js"],
      "css": ["assets/editor.css"]
    }
  }
}

Automatic Namespacing​

To prevent conflicts between different apps, SitePack automatically namespaces your element IDs internally. If your app UUID is awesome-app and your element ID is my-element, it will be stored internally as [uuid].my-element. However, in your code and manifest, you only use your clean handle (my-element).

The Preview Template (Twig)​

SitePack renders your block in the editor using the preview_template specified in your manifest. This template receives the element_settings as a context variable, allowing you to show real-time changes as the merchant adjusts settings.

Example my_block_preview.html.twig:

<div class="my-custom-element" style="color: {{ element_settings.text_color|default('#000') }}">
    <h3>{{ element_settings.title|default('Hello World') }}</h3>
    <p>{{ element_settings.description }}</p>
</div>

SitePackAdminSDK​

In the editor environment, a global SitePackAdmin object is available. This SDK allows your app's scripts to interact with the SitePack editor safely.

Example: Opening a Media Picker​

// assets/editor.js
const media = await SitePackAdmin.media.pick({ type: 'image' });
if (media) {
    await SitePackAdmin.element.updateSettings({ image_id: media.id });
}

Key SDK Modules​

  • SitePackAdmin.media: Interact with the media library (pick, upload).
  • SitePackAdmin.element: Manage the settings and state of the current editor element.
  • SitePackAdmin.notifications: Show toast notifications or alerts to the merchant.

Security and Sandboxing​

  • CSP: SitePack enforces a strict Content Security Policy. External scripts are blocked; all assets must be bundled within your app.
  • Origin Isolation: Editor previews are served from a separate static domain to prevent cross-context data leaks.
  • Shadow DOM: SitePack may use Shadow DOM to ensure your app's CSS doesn't leak into the rest of the editor UI.

Next Steps​