Studio Messenger

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

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

``bash
npm install @contentstack/studio-messenger
`

Usage

$3

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

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

$3

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

$3

`typescript
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 / }
});
`

$3

`typescript
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

$3

#### 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

$3

#### 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

$3

`typescript
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

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

$3

`bash
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.

$3

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