Salesforce B2C Commerce 24.7 > Developing Your Site > Page Designer > Develop a Custom Attribute Editor

Custom Attribute Editor Events

Each custom attribute editor is wrapped in a host component that contains an HTML iframe element. The iframe encapsulates the code and styling of the editor and represents a self-contained sandbox environment in which the editor runs so that different custom attribute editors on the same page don't interfere with each other. The host and the custom attribute editor in the iframe communicate by passing events back and forth on a special messaging channel.

For information about the messaging channel implemented for Page Designer custom attribute editors, see Channel Messaging. For information about the messaging API used to send and receive the events, see Messaging API. Page Designer adds some management code to the iframe that includes a subscribe method and an emit method that send predefined events with serializable payloads back and forth between the host and the editor.

subscribe()

Subscribes to events sent from the host to the editor. You can subscribe for a certain event type and when that event is sent from the host, a callback is invoked that uses a payload and optional context.


            subscribe:Interface
type SandboxSubscribe = (type: string, callback: (payload?: any, context?: SandboxContext) => void, source?: any) => () => void;
 
interface SandboxContext {
  transfer?: Transferable[]; // @see https://developer.mozilla.org/en-US/docs/Web/API/Transferable
  source?: any; // Event sourcing should only be required in rare cases
}


            subscribe Example
subscribe('sfcc:ready', (payload, context) => {
  // ...
});

emit()

Sends events from the editor to the host.


            emit:Interface
type SandboxEmit = (message: SandboxMessage, callback?: (payload: any) => void) => void;
 
interface SandboxMessage {
  type: string;
  payload?: any;
  source?: any;
  transfer?: Transferable | Transferable[];


            emit Example
emit({
  type: 'sfcc:breakout',
  payload: {
    id: 'myBreakoutId',
    title: '
  }
}, ({ type, value }) => { // ... });

Table 1. Events Emitted by the Host
Event	Meaning	Payload
`sfcc:ready`	The custom attribute editor is initialized. All the scripts and styles have been loaded into the editor's environment. When the host emits this event, it doesn't necessarily mean that all asynchronously loaded assets and code have finished loading. For some components, you might need to manually listen to browser events, such as load or DOMContentLoaded, to get more information. The `sfcc:ready` event includes information required to display the editor, such as initial value, configuration data, data locale, display locale, and initial validity.	`{ value: {<object of arbitrary structure>}; config: {<object of arbitrary structure>}; isRequired: boolean; isDisabled: boolean; isValid: boolean; dataLocale: string; displayLocale: string; }`
`sfcc:value`	The value of the attribute. Not sent on the initial load. Sent only when the value changes because of external modifications.	`{<object of arbitrary structure>}`
`sfcc:required`	Indicates whether this attribute is required. Not sent on the initial load. Sent only when the required status changes after the initialization ready phase. The custom attribute editor might use this information to display certain styling or indicators in the editor.	`boolean`
`sfcc:disabled`	Indicates whether this attribute is disabled. Not sent on the initial load. Sent only when the disabled status changes after the initialization ready phase. The custom attribute editor might use this information to render elements differently or display certain styling or indicators in the editor.	`boolean`
`sfcc:valid`	Indicates whether the value of the attribute is valid. Not sent on the initial load. Sent only when the validity status changes after the initialization ready phase.	`boolean`

Table 2. Events Emitted by the Custom Attribute Editor
Event	Meaning	Payload
`sfcc:value`	The value of the attribute. Sent when the value changes inside the editor. Page Designer requires that the value be a plain JavaScript object.	`{<object of arbitrary structure>}`
`sfcc:valid`	Indicates whether the value of the attribute is valid. Can include an error message.	`{ valid: boolean, message: string }`
`sfcc:interacted`	Indicates that the user has interacted with the custom attribute editor. The editor is implicitly marked as interacted when it is blurred, for example, when the editor's `contentWindow` loses focus. Page Designer supports an interacted (or touched) state for form elements. This state marks a field that a user already interacted with, for example, by tabbing through it. Being able to mark a field as touched allows for error messages in forms to be hidden initially and only display for fields with which a user has interacted.	`void`