Developing Apps using Message Channel API

The Sheet component can interoperate with other Lightning components and Visualforce pages on a Lightning page where it has been placed through the Lightning Message Service mechanism of the Salesforce platform. This makes it possible to create applications that update elements in the page in response to user actions in the Sheet component, or conversely update the content of the Sheet component according to actions on the page.

To create an application that interacts with the Sheet component, it is necessary to develop Lightning components or Visualforce pages. For details on how to develop them, please refer to the Salesforce developer documentation.

Subscribing Fired Events

Actions taken in the Sheet component can be notified to external programs as events. Custom programs can subscribe to the Message Channel where these events will be fired to interact with the actions in the sheet.

In the case of the Lightning Web component, the code to subscribe to events in the Sheet component is as follows:

import { LightningElement, wire } from "lwc";
import {
  subscribe,
  unsubscribe,
  APPLICATION_SCOPE,
  MessageContext
} from "lightning/messageService";

// Message Channel to catch events of focused cell in the sheet
import MC_FOCUS_CELL from "@salesforce/messageChannel/msmxSheet__focusCell__c";

// A component that subscribes the events
export default class MyComponent extends LightningElement {
  @wire(MessageContext)
  messageContext;

  subscr = null;

  connectedCallback() {
    // Create subscription to Message Channel
    // For details, please refer to the developer documents of Salesforce Lightning Web Component
    this.subscr = subscribe(
      this.messageContext,
      MC_FOCUS_CELL,
      (msg) => this.handleFocusCell(msg),
      { scope: APPLICATION_SCOPE }
    );
  }

  disconnectedCallback() {
    // Unsubscribe the subscription to Message Channel
    if (this.subscr) {
      unsubscribe(this.subscr);
    }
    this.subscr = null;
  }

  handleFocusCell(message) {
    // do something important
    console.log(message.cell.recordId);
  }
}

For a Visualforce page, the code to subscribe to the events of the Sheet component is as follows:

<apex:page>
  <div>
    <p>Subscribe to SampleMessageChannel </p>
    <button onclick="startSubscription()">Subscribe</button>
    <p>Unsubscribe from subscription</p>
    <button onclick="stopSubscription()">Unsubscribe</button>
    <br/>
    <br/>
    <p>Received message:</p>
    <textarea id="messageReceived" rows="10" />
  </div>
  <script>
    // Message Channel to catch events of focused cell in the sheet
    var MC_FOCUS_CELL = "{!$MessageChannel.msmxSheet__focusCell__c}";
    var subscr = null;

    function handleFocusCell(message) {
      console.log(message.cell.recordId);
      document.querySelector("#messageReceived").value = JSON.stringify(message, null, 2);
    }

    function startSubscription() {
      // Create subscription to Message Channel
      // For details, please refer to the developer documents of Salesforce Visualforce page
      subscr = sforce.one.subscribe(MC_FOCUS_CELL, handleFocusCell, { scope: "APPLICATION" });
    }

    function stopSubscription() {
      // Unsubscribe the subscription to Message Channel
      if (subscr) {
        sforce.one.unsubscribe(subscr);
        subscr = null;
      }
    }
  </script>
</apex:page>

In order to fire events externally from the Sheet component through the Message Channel, the "Publish Events in Message Channel" property must be checked when the component is placed in the page.

Event Types and Corresponding Message Channels

Mashmatrix Sheet currently supports the following events and their Message Channels.

Select Records

Event to notify the change of selected records

Message Channel Name

msmxSheet__selectRecords__c

Payload of Event Message

• componentId - Unique ID within the page representing the Sheet component. The value set in the Sheet component property settings is used.

• bookId - ID of the book where selection changed

• sheetId - ID of the sheet where selection changed

• records - List of records in selection

• recordIds - List of record IDs in selection

Load Complete

Event to notify data load completion in the sheet

Message Channel Name

msmxSheet__loadComplete__c

Payload of Event Message

• componentId - Unique ID within the page representing the Sheet component. The value set in the Sheet component property settings is used.

• bookId - ID of the book where the data load completed

• sheetId - ID of the sheet where the data load completed

• records - List of loaded records

• recordIds - List of loaded record IDs

Focus Cell

Event to notify the change of cell focus

Message Channel Name

msmxSheet__focusCell__c

Payload of Event Message

• componentId - Unique ID within the page representing the Sheet component. The value set in the Sheet component property settings is used.

• bookId - ID of the book where cell focus changed

• sheetId - ID of the sheet where cell focus changed

• cell - Information object for the focused cell

  • recordId - ID of the record which contains the cell

  • rowIndex - Row index position of the cell (of all pages)

  • colIndex - Column index position of the cell

  • columnName - Name of the column of the cell

  • value - Value displayed in the cell

• record - Stores the record information on focused cell if the cell is in a record

Fire Custom Event

Event fired when custom event action links set in sheet cells are clicked, or when action buttons that fire custom events are clicked

Message Channel Name

msmxSheet__fireCustomEvent__c

Payload of Event Message

• componentId - Unique ID within the page representing the Sheet component. The value set in the Sheet component property settings is used.

• bookId - ID of the book where the custom event was fired

• sheetId - ID of the sheet where the custom event was fired

• eventName - Contains the event name set in the action button/link configuration

• records - (For custom events from action buttons) List of records selected in the sheet

• recordIds - (For custom events from action buttons) List of record IDs selected in the sheet

• record - (For custom events from action links) Contains information for the record containing the clicked link

• recordId - (For custom events from action links) Contains the ID of the record containing the clicked link

Setting Parameters

It is possible to set and send parameters from the outside to the Sheet component placed in the Lightning page. To use a parameter, the sheet in the Sheet component must reference the parameter value of the same name as the reference value in the filter.

To set parameters, a Message Channel is used as in the case of event subscriptions. Custom programs will set parameters by publishing a message to this Message Channel.

In the case of the Lightning Web component, the code to set parameters to the Sheet component would look like this:

import { LightningElement, wire } from "lwc";
import { publish, MessageContext } from "lightning/messageService";

import MC_SET_PARAMETERS from "@salesforce/messageChannel/msmxSheet__setParameters__c";

export default class PublishExample extends LightningElement {
  @wire(MessageContext)
  messageContext;

  handleSubmit() {
    publish(this.messageContext, MC_SET_PARAMETERS, {
      parameters: {
        accountName: "Acme"
      }
    });
  }
}

For a Visualforce page, the code to set parameters to the Sheet component is as follows:

<apex:page>
  <div>
    <input type="text" id="acccountName" value="Acme" />
    <p>Publish to MessageChannel </p>
    <button onclick="publishMessage()">Publish</button>
  </div>
  <script>
    // Message Channel to send parameters to Sheet component
    var MC_SET_PARAMETERS = "{!$MessageChannel.msmxSheet__setParameters__c}";
    function publishMessage(message) {
      sforce.one.publish(MC_SET_PARAMETERS, {
        parameters: {
          accountName: document.querySelector("#acccountName").value,
        }
      });
    }
  </script>
</apex:page>

Message Channel for Setting Parameters

Message Channel Name

msmxSheet__setParameters__c

Payload of Event Message

• componentId - ID representing the Sheet component to set parameters for. Set the value specified in the Sheet component property settings. If not specified, parameters will be set for all Sheet components on the page.

• parameters - An arbitrary JSON-formatted object specifying parameters. The format is { "parameter name": "parameter value", ... }.

• partial - Specify true for partial updates instead of replacing all parameter values.

• forceLoad - Specify true to force reloading of the active sheet.

Execute Commands

It is possible to send operation commands from the outside to the Sheet component placed in the Lightning page.

Similar to the parameter setting case, commands are executed by publishing a message to the Message Channel.

In the case of the Lightning Web component, the code to send commands to the Sheet component is as follows:

import { LightningElement, wire } from "lwc";
import { publish, MessageContext } from "lightning/messageService";

import MC_EXECUTE_COMMAND from "@salesforce/messageChannel/msmxSheet__executeCommand__c";

export default class CommandExample extends LightningElement {
  @wire(MessageContext)
  messageContext;
  
  @api
  bookId;
  
  sheetId = 's1';

  handleFocusSheet() {
    publish(this.messageContext, MC_EXECUTE_COMMAND, {
      command: "focusSheet",
      arguments: {
        bookId: this.bookId,
        sheetId: this.sheetId
      }
    });
  }
}

For a Visualforce page, the code to send commands to the Sheet component is as follows:

<apex:page>
  <div>
    <p>Click to change focus</p>
    <a onclick="focusSheet('s1')">Sheet #1</a>
    <a onclick="focusSheet('s2')">Sheet #2</a>
  </div>
  <script>
    // Message Channel to send parameter settings to Sheet
    var bookId = 'your book id is here';
    var MC_EXECUTE_COMMAND = "{!$MessageChannel.msmxSheet__executeCommand__c}";
    function focusSheet(sheetId) {
      sforce.one.publish(MC_EXECUTE_COMMAND, {
        command: "focusSheet",
        arguments: {
          bookId: bookId,
          sheetId: sheetId
        }
      });
    }
  </script>
</apex:page>

Message Channel for Command Execution

Message Channel Name

msmxSheet__executeCommand__c

Payload of Event Message

• componentId - ID representing the target Sheet component for command execution. Set the value specified in the Sheet component property settings. If not specified, command execution will be requested for all Sheet components on the page.

• command - Command name to execute.

• arguments - Arguments to pass to the command. Passed as a JSON-formatted object, but the required information differs depending on the command to execute. The format is { "argument name": "argument value", ... }.

Types of Executable Commands

Mashmatrix Sheet currently supports the following commands.

Focus Sheet

Focus the specified sheet. If the target sheet is inactive (not in the front of tabs / not the target of single display), it becomes active and is displayed in the front. If the specified sheet is in a hidden state or does not exist, nothing is executed.

Command Name

focusSheet

Command Arguments

• bookId - Book ID of the book containing the sheet to focus.

• sheetId - Sheet ID of the sheet to focus.

Save Records

Saves the record data being edited in the specified sheet. If there are no records being edited, nothing is executed.

Command Name

saveRecords

Command Arguments

• bookId - Book ID of the book containing the sheet to save records.

• sheetId - Sheet ID of the sheet to save records.

Command execution requests sent at times when command execution would be problematic, such as during application loading or dialog display, are discarded without notification to the requesting program.