Drupal Canvas Extensions API

JavaScript library for building Drupal Canvas extensions. Extensions are embedded web applications that can access and respond to data inside the Drupal Canvas app in real-time.

• Installation
• Getting started
• Example
• API
  • getPreviewHtml()
  • subscribeToPreviewHtml(callback)
  • getSelectedComponentUuid()
  • subscribeToSelectedComponentUuid(callback)

Installation

npm install @drupal-canvas/extensions

Getting started

To build a Drupal Canvas extension, create a web application with your technology of choice, and make sure it can be embedded in an iframe.

Then create a Drupal module with a [your-module-name].canvas_extension.yml file to define your extension's metadata:

canvas_test_extension: # ID of your extension. You can specify multiple extensions in this file.
  name: Example Extension
  description: A brief description of what your example does.
  url: index.html # Path to local HTML file shipped in your module's codebase, or a remote URL.
  icon: icon.svg # Path to local SVG file shipped in your module's codebase.
  api_version: 1.0

Example

For a full example, see the canvas_test_extension test module in the Drupal Canvas codebase.

API

getPreviewHtml()

Get the current preview HTML.

Returns: Promise<string>

import { getPreviewHtml } from "@drupal-canvas/extensions";

const html = await getPreviewHtml();
console.log(html);

subscribeToPreviewHtml(callback)

Subscribe to preview HTML changes. The callback is called whenever the preview HTML updates.

Parameters:

• callback: (html: string) => void - Function called with the updated HTML

Returns: () => void - Unsubscribe function

import { subscribeToPreviewHtml } from "@drupal-canvas/extensions";

const unsubscribe = subscribeToPreviewHtml((html) => {
  console.log("Preview HTML updated:", html);
});

// Later, when you want to stop listening:
unsubscribe();

getSelectedComponentUuid()

Get the UUID of the currently selected component.

Returns: Promise<string | undefined>

import { getSelectedComponentUuid } from "@drupal-canvas/extensions";

const uuid = await getSelectedComponentUuid();
if (uuid) {
  console.log("Selected component:", uuid);
} else {
  console.log("No component selected");
}

subscribeToSelectedComponentUuid(callback)

Subscribe to selected component UUID changes. The callback is called whenever the user selects a different component.

Parameters:

• callback: (uuid: string | undefined) => void - Function called with the selected component UUID

Returns: () => void - Unsubscribe function

import { subscribeToSelectedComponentUuid } from "@drupal-canvas/extensions";

const unsubscribe = subscribeToSelectedComponentUuid((uuid) => {
  if (uuid) {
    console.log("Component selected:", uuid);
  } else {
    console.log("No component selected");
  }
});

// Later, when you want to stop listening:
unsubscribe();