Custom UI Control Events

The host wrapper element that encapsulates a custom UI control communicates with the control by passing events back and forth on a special messaging channel. For information about the messaging channel implemented for Page Designer custom UI controls, see Channel Messaging. For information about the messaging API used to send and receive the events, see Messaging API.

Table 1. Events Emitted By the Host
Event Meaning Payload
sfcc:ready The control is initialized. All the scripts and styles have been loaded into the control'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 control, 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 initial load. Sent only if the value changes because of external modifications. {<object of arbitrary structure>}
sfcc:required Indicates whether this attribute is required or not. Not sent on initial load. Sent only if the required status changes after the initialization ready phase. The control might use this information to display certain styling or indicators within the control. boolean
sfcc:disabled Indicates whether this attribute is disabled or not. Not sent on initial load. Sent only if the disabled status changes after the initialization ready phase. The control might use this information to render elements differently, or display certain styling or indicators within the control. boolean
sfcc:valid Indicates whether the value of the attribute is valid. Not sent on initial load. Sent only if the validity status changes after the initialization ready phase. boolean
Table 2. Events Emitted by the UI Control
Event Meaning Payload
sfcc:value The value of the attribute. Sent if the value changes inside the control. 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 control. The control is implicitly marked as interacted when it is blurred, for example, when the control's contentWindow loses focus. Page Designer supports an interacted (or touched) state for form elements. This state marks a field a user already interacted with by, for example, tabbing through it. This allows for error messages in forms to be hidden initially and only display for fields with which a user has interacted. void