Rasterex API/docs/components/placement/symbols

Symbols

Open, close, or toggle the canvas symbols panel from the host application.

Overview

Use symbolsControl when the host needs to control the symbols panel inside the active canvas session.

This integration is command-based. The host sends open, close, or toggle to the current iframe session and can include an optional requestId for correlation.

If you need to manage the reusable symbol library itself, use the separate Symbol Management Admin module instead of the placement message flow.

  • Command-based: Use open, close, or toggle depending on the panel state you want.
  • Canvas session scoped: Send the command to the same iframe instance that owns the current document.
  • Observable result: Watch symbolsControlResult to confirm whether the panel ended up opened or closed.

Commands

Send symbolsControl with the required command field.

Open Symbols Panel

iframe.contentWindow.postMessage({
  type: 'symbolsControl',
  payload: { command: 'open', requestId: 'symbols-1' }
}, '*');

Close Symbols Panel

iframe.contentWindow.postMessage({
  type: 'symbolsControl',
  payload: { command: 'close', requestId: 'symbols-2' }
}, '*');

Toggle Symbols Panel

iframe.contentWindow.postMessage({
  type: 'symbolsControl',
  payload: { command: 'toggle', requestId: 'symbols-3' }
}, '*');

Result Event

The canvas emits symbolsControlResult after it applies the command.

Use the returned payload to confirm success, inspect the resolved command, and determine whether the panel is open through the opened flag.

Handle symbolsControlResult

window.addEventListener('message', (event) => {
  if (event.data.type !== 'symbolsControlResult') return;

  const { success, command, opened, requestId, error } = event.data.payload;
  console.log('symbolsControlResult', { success, command, opened, requestId, error });
});

Recommended Workflow

Keep the host flow simple and send the command only after the canvas is ready.

  • 11. Wait for canvas readiness: Make sure the iframe is loaded and the canvas session is active.
  • 22. Send a symbols command: Use open, close, or toggle based on the interaction your product needs.
  • 33. Observe the result: Listen for symbolsControlResult and read opened to confirm the final panel state.
  • 44. Correlate when needed: Include requestId if your host needs to match requests and results in logs.

Complete Example

This example wires three host buttons to the current canvas iframe and logs the result event.

const viewerOrigin = '*';
const iframe = document.querySelector('iframe');

function sendSymbolsControl(command) {
  if (!iframe?.contentWindow) return;

  iframe.contentWindow.postMessage({
    type: 'symbolsControl',
    payload: {
      command,
      requestId: 'symbols-' + command + '-' + Date.now(),
    },
  }, viewerOrigin);
}

document.getElementById('openSymbolsBtn').addEventListener('click', () => {
  sendSymbolsControl('open');
});

document.getElementById('closeSymbolsBtn').addEventListener('click', () => {
  sendSymbolsControl('close');
});

document.getElementById('toggleSymbolsBtn').addEventListener('click', () => {
  sendSymbolsControl('toggle');
});

window.addEventListener('message', (event) => {
  if (event.data.type !== 'symbolsControlResult') return;
  console.log('Symbols result', event.data.payload);
});
Complete Example