Studio Messenger

A communication package that handles messaging between the Studio platform and iframe webpages using postMessage API.

• Studio Messenger
  • Overview
  • Features
  • Installation
  • Usage
    • Basic Setup
    • Available Event Managers
    • Sending Messages
    • Listening for Messages
  • API Reference
    • Constants
      • Channel IDs
      • Query Parameters
    • Event Types
      • Studio Events (POST_MESSAGE_EVENTS)
      • Visual Builder Events (VISUAL_BUILDER_POST_MESSAGE_EVENTS)
      • Built-in Canvas Events (COMPOSABLE_STUDIO_BUILT_IN_CANVAS_POST_MESSAGE_EVENTS)
    • Event Data Types
  • Development
    • Building
    • Development Mode
    • Linting
  • Architecture
    • Channel Flow

Overview

This package provides a robust messaging system for communication between different parts of the Studio ecosystem:

• Studio - The main editing interface
• Visual Builder - The visual editing interface
• Built-in Canvas - Embedded canvas components
• Popup Windows - Modal dialogs and popups

Features

• Bidirectional Communication - Send and receive messages between iframes and parent windows
• Multiple Channels - Separate communication channels for different contexts
• Type Safety - Full TypeScript support with typed event data
• Event Management - Built on @contentstack/advanced-post-message for reliable messaging
• Debug Support - Optional debug mode for development

Installation

npm install @contentstack/studio-messenger

Usage

Basic Setup

The package automatically initializes event managers when loaded in a browser environment:

import {
  composableStudioEventManager,
  visualBuilderEventManager,
  composableStudioPopupEventManager,
  composableStudioBuiltInCanvasEventManager
} from '@contentstack/studio-messenger';

Available Event Managers

• composableStudioEventManager - Main Studio communication
• visualBuilderEventManager - Visual Builder communication
• composableStudioPopupEventManager - Popup window communication
• composableStudioBuiltInCanvasEventManager - Built-in canvas communication

Sending Messages

import { composableStudioEventManager, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';

// Send a highlight node event
composableStudioEventManager?.emit(POST_MESSAGE_EVENTS.HIGHLIGHT_NODE, {
  nodeId: 'my-node-id',
  highlight: true
});

// Send a transform operation
composableStudioEventManager?.emit(POST_MESSAGE_EVENTS.TRANSFORM_OPERATION, {
  operation: 'insert-node',
  data: { /* operation data */ }
});

Listening for Messages

import { visualBuilderEventManager, VISUAL_BUILDER_POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';

// Listen for composition saved events
visualBuilderEventManager?.on(VISUAL_BUILDER_POST_MESSAGE_EVENTS.COMPOSITION_SAVED, (data) => {
  console.log('Composition saved:', data);
  // Handle the saved composition
});

API Reference

Constants

Channel IDs

• COMPOSABLE_STUDIO_CHANNEL_ID - Main Studio channel
• VISUAL_BUILDER_CHANNEL_ID - Visual Builder channel
• COMPOSABLE_STUDIO_POPUP_CHANNEL_ID - Popup channel
• COMPOSABLE_STUDIO_BUILT_IN_CANVAS_CHANNEL_ID - Built-in canvas channel

Query Parameters

• COMPOSABLE_STUDIO_QUERY_PARAM - Available query parameters for configuration

Event Types

Studio Events (POST_MESSAGE_EVENTS)

• HIGHLIGHT_NODE - Highlight/unhighlight nodes
• SET_ACTIVE_NODE - Set the currently active node
• TRANSFORM_OPERATION - Apply transformations to nodes
• REGISTER_COMPONENTS - Register new components
• GET_NODE_STYLE - Retrieve node styles
• UPDATE_DATA_SOURCE - Update data sources
• APPLY_OPERATION - Apply operations
• GET_ACTIVE_BREAKPOINT - Get current breakpoint
• REGISTER_BREAKPOINTS - Register breakpoint definitions
• SET_CURSOR_TYPE - Set cursor type
• HIGHLIGHT_SLOT_NODE - Highlight slot nodes
• UPDATE_BINDING_ERRORS - Update binding validation errors
• HIDDEN_COMPONENT_NOTIFICATION - Notify about hidden components

Visual Builder Events (VISUAL_BUILDER_POST_MESSAGE_EVENTS)

• REFETCH_SPEC - Request spec refetch
• COMPOSITION_SAVED - Composition save notification
• OPEN_IN_COMPOSABLE_STUDIO_EVENT_MESSAGE - Open in Studio

Built-in Canvas Events (COMPOSABLE_STUDIO_BUILT_IN_CANVAS_POST_MESSAGE_EVENTS)

• REQUEST_FOR_COMPOSITION_CONFIG - Request composition configuration

Event Data Types

interface OpenComposableStudioFromVBEventData {
  compositionEntryUid: string;
  windowFeatures?: string;
  fetchCompositionData: FetchCompositionData | null;
}

interface CompositionSavedEventData {
  entryUid: string;
  contentTypeUid: string;
  locale: string;
}

interface HiddenElementNotificationEventData {
  action: "open" | "close";
  uid: "__all__" | string;
}

Development

Building

npm run build

Development Mode

npm run dev

Linting

npm run lint
npm run lint:fix

Architecture

The package uses a singleton pattern to manage event managers across the application. Each manager is stored in window.__csMessengerListeners__ to ensure consistent communication channels.

Channel Flow

Studio ↔ Visual Builder
        ↕
   Built-in Canvas
        ↕
    Popup Windows