app_custom_bm_extensions
└─> cartridge
└─> app_custom_bm_extensions.properties

## cartridge.properties for cartridge app_custom_bm
#Mon Apr 29 19:46:1 CEST 2023
demandware.cartridges.app_custom_bm_extensions.multipleLanguageStorefront=true
demandware.cartridges.app_custom_bm_extensions.id=app_custom_bm

// Placeholder - No extra content at the moment.

{
  "name": "Custom Attribute Editor",
  "description": "",
  "group": "Custom",
  "attribute_definition_groups": [
    {
      "id": "group1",
      "name": "An attribute group",
      "description": "",
      "attribute_definitions": [
        {
          "id": "playground",
          "name": "Playground",
          "type": "custom",
          "required": false,
          "editor_definition": {
            "type": "com.acme.customEditor",
            "configuration": {}
          }
        }
      ]
    }
  ],
  "region_definitions": []
}

app_custom_bm_extensions/cartridge/experience/editors/com/acme/

{
  "name": "My Custom Editor (inline)",
  "description": "",
  "resources": {
    "scripts": [
      "/experience/editors/com/acme/customEditorClient.js"
    ],
    "styles": []
  }
}

'use strict';

var URLUtils = require('dw/web/URLUtils');
var PageMgr = require('dw/experience/PageMgr');
var HashMap = require('dw/util/HashMap');

/**
 * Init the ACME Custom Editor (inline)
 * @param editor
 *
 * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/page_designer/b2c_custom_ui_cntrl_script.html
 */
module.exports.init = function (editor) {
  // This is important because it sets the asset URLs to the non-versioned URLs...
  editor.configuration.put('baseUrl', URLUtils.staticURL('/').https().toString());
};

() => {
  subscribe('sfcc:ready', async () => {
    console.log('sfcc:ready');
    let tempElement = document.createElement('h1');
    tempElement.innerText='Hello from customEditorClient.js';
    document.body.append(tempElement);
  });
};

app_custom_bm_extensions
└─> cartridge
    ├─> experience
    │   ├─> components
    │   │   ├── customAttributeEditor.js
    │   │   └── customAttributeEditor.json
    │   └─> editors
    │       └─> com
    │           └─> editors
    │               └─> acme
    │                   ├── customEditor.js
    │                   └── customEditor.json
    └─> static
        └─> default
            └─> experience
                └─> com
                    └─> editors
                        └─> acme
                            └── customEditorClient.js

app_custom_bm_extensions/cartridge/static/default/apps/custom-editors/

(() => {
  /**
   * This file is what SFCC initially loads into the custom editor iFrame.
   * From here we inject our React bundle and, do some rudimentary data handling.
   *
   * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/page_designer/b2c_host_events_custom_attr_editor.html
   */
  subscribe('sfcc:ready', async () => {

    // This is the path to the editor app's dist assets in our static/default directory.
    const EDITOR_APP_PATH = 'apps/custom-editors/';

    /**
     * Start our React injection logic.
     *
     * Essentialy we're mimicing what is normally in the index.html file of the dist, but
     * as we don't have any template we need to inject the scripts using JS.
     */

    // Create our React root element.
    const reactRoot = document.createElement('div');
    reactRoot.id = "root";
    document.body.appendChild(reactRoot);

    // React critical scripts
    const scripts = ['runtime', 'polyfills', 'vendor', 'main'];

    // Iterate over our predefined JS files and insert them one after the other.
    for (let i = 0; i < scripts.length; i++) {
      let scriptName = scripts[i];
      let reactScriptElm = document.createElement('script');
      reactScriptElm.setAttribute('type', 'text/javascript');
      reactScriptElm.setAttribute('src', config.baseUrl + EDITOR_APP_PATH + scriptName + '.js');
      document.head.appendChild(reactScriptElm);
    }

    // Insert our CSS to the iFrame <head />
    const reactStyles = document.createElement('link');
    reactStyles.setAttribute('rel', 'stylesheet');
    reactStyles.setAttribute('href', config.baseUrl + EDITOR_APP_PATH + 'styles.css');

    document.body.appendChild(reactStyles);
  });
})();

   app_custom_bm_extensions
    └─> cartridge
        ├─> experience
        │   ├─> components
        │   │   ├── customAttributeEditor.js
        │   │   └── customAttributeEditor.json
        │   └─> editors
        │       └─> com
        │           └─> editors
        │               └─> acme
        │                   ├── customEditor.js
        │                   └── customEditor.json
        └─> static
            └─> default
+               ├─> apps
+               │   └─> custom-editors
+               │       ├── main.js
+               │       ├── polyfills.js
+               │       ├── runtime.js
+               │       ├── styles.css
+               |       ├── [...all the other React build output]
+               │       └── vendor.js
                └─> experience
                    └─> com
                        └─> editors
                            └─> acme
                                └── customEditorClient.js

const SimpleCustomAttributeEditorEvents = () => {

  const handleOnClick = () => {
    window.emit({
      type: 'sfcc:value',
      payload: {
        newValue: new Date()
      }
    });
  }

  return (
    <div>
      <button onClick={() => handleOnClick()}>Test me</button>
    </div>
  )
}

 {
  "editor_definition": {
    "type": "com.acme.customEditor",
    "configuration": {}
  }
}

  {
    "editor_definition": {
      "type": "com.acme.customEditor",
-     "configuration": {}
+     "configuration": {
+       "editorType": "playground"
+     }
    }
  }

 (() => {
   /**
    * This file is what SFCC initially loads into the custom editor iFrame.
    * From here we inject our React bundle and, do some rudimentary data handling.
    *
    * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/page_designer/b2c_host_events_custom_attr_editor.html
    */
-   subscribe('sfcc:ready', async () => {
+   subscribe('sfcc:ready', async ({ value, config, isDisabled, isRequired, dataLocale, displayLocale }) => {

+    /**
+     * Attach the existing value (if available) for the component and some other
+     * data for the React app to consume later.
+     */
+    window.amce = {
+      originalValue: value,
+      config,
+      isDisabled,
+      isRequired,
+      dataLocale,
+      displayLocale,
+    }
+
     // This is the path to the editor app's dist assets in our static/default directory.
     const EDITOR_APP_PATH = 'apps/custom-editors/';

     /**
      * Start our React injection logic.
      *
      * Essentialy we're mimicing what is normally in the index.html file of the dist, but
      * as we don't have any template we need to inject the scripts using JS.
      */

     // Create our React root element.
     var reactRoot = document.createElement('div');
     reactRoot.id = "root";
     document.body.appendChild(reactRoot);

     // React critical scripts
     var scripts = ['runtime', 'polyfills', 'vendor', 'main'];

     // Iterate over our predefined JS files and insert them one after the other.
     for (var i = 0; i < scripts.length; i++) {
       var scriptName = scripts[i];
       var reactScriptElm = document.createElement('script');
       reactScriptElm.setAttribute('type', 'text/javascript');
       reactScriptElm.setAttribute('src', config.baseUrl + EDITOR_APP_PATH + scriptName + '.js');
       document.head.appendChild(reactScriptElm);
     }

     var reactStyles = document.createElement('link');
     reactStyles.setAttribute('rel', 'stylesheet');
     reactStyles.setAttribute('href', config.baseUrl + EDITOR_APP_PATH + 'styles.css');

     document.body.appendChild(reactStyles);
   });
 })();

import { Navigate, Route, Routes, useLocation } from "react-router-dom";

export function App() {

  const location = useLocation();
  const definition = window.acme;
  const requestedRoute = '/editor/' + definition.editorType;

  if (!definition || !requestedRoute) {
    return <ErrorPage message={'Missing editor/page configuration'} />;
  }

  if (requestedRoute && requestedRoute !== location.pathname) {
    return <Navigate to={requestedRoute} />;
  }

  return (
    <Routes>
      <Route path={'/'} element={<HomePage />} />
      <Route path={'/editor/:editorId'} element={<EditorComponent definition={definition} />} />
      <Route path={'*'} element={<ErrorPage message={'Page not found'} />} />
    </Routes>
  )
}

// Set up a map of editorTypes string to a specific component.
const availableEditors = {
  'example': ExampleEditor,
}

export const EditorWrapper = ({ definition }) => {

  // Grabs the editorType from the URL parameters we set in App.jsx
  const { editorType } = useParams();

  // Grab the config from our definition.
  const { config } = definition;

  // Presense checks
  if(!editorType || !availableEditors[editorType]) {
    return (
      <FourOhFourPage
        message={`
          Unsupported editor requested with id: "${editorType}". Please check the
          [component].json file to be one of our supported editors.
        `}
      />
    );
  }

  // Map to component
  const EditorComponent = availableEditors[editorType];

  return (
      <EditorComponent config={config} />
  )
}

/**
 * Events Emitted by the Custom Attribute Editor
 *
 * The vendor specified event names for the various events we emit to
 * Page Designer.
 *
 * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2Fcontent%2Fb2c_commerce%2Ftopics%2Fpage_designer%2Fb2c_custom_attr_editor.html&cp=0_7_7_4
 */
export const SFCC_EVENT_TYPES = {
  EDITOR_INTERACTED: 'sfcc:interacted',
  VALUE_VALID: 'sfcc:valid',
  VALUE_APPLY: 'sfcc:value'
}

/**
 * Communicate updates to Page Designer
 *
 * @param {Object} newValue - The new/existing data value for this attribute.
 * @param {boolean} [isValid=true] - Update the current validity state of the attribute in Page Designer.
 * @param {String} validityMessage - (Optional) A message to pass to Page Designer that will render as the error message.
 */
export const handleChangeEvent = (newValue, isValid = true, validityMessage) => {
  handleInteraction();
  handleValidity(isValid, validityMessage);
  if (isValid) {
    handleUpdate(newValue);
  }
};

/**
 * 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.
 */
const handleInteraction = () => {
  window.emit({
    type: SFCC_EVENT_TYPES.EDITOR_INTERACTED
  });
};

/**
 * Indicates whether the value of the attribute is valid. Can include an error message.
 *
 * @param {boolean} validity - If the field is valid or not
 * @param {string} message - The error message passed to override the default
 */
const handleValidity = (validity, message) => {
  window.emit({
    type: SFCC_EVENT_TYPES.VALUE_VALID,
    payload: {
      valid: validity,
      message: message
    }
  });
};

/**
 * The value of the attribute. Sent when the value changes inside the editor.
 * Page Designer requires that the value be a plain JavaScript object.
 *
 * Please note: This event will mark the sidebar as having changed, clicking save
 * on the sidebar will trigger a rerender of the editor.
 *
 * @param {object} newValue - The new value to be passed to SFCC.
 */
const handleUpdate = (newValue) => {
  window.emit({
    type: SFCC_EVENT_TYPES.VALUE_APPLY,
    payload: newValue
  });
};

import { handleChangeEvent } from "../lib/custom-attribute-editor-client";

const SimpleCustomAttributeEditorEvents = () => {

  const handleOnClick = () => {
    handleChangeEvent({
      newValue: new Date()
    });
  }

  return (
    <div>
      <button onClick={() => handleOnClick()}>Test me</button>
    </div>
  )
}

'use strict';

var URLUtils = require('dw/web/URLUtils');

/**
 * ACME Custom Editor (breakout)
 * @param editor
 *
 * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2Fcontent%2Fb2c_commerce%2Ftopics%2Fpage_designer%2Fb2c_custom_attr_editor.html&cp=0_7_7_4
 */
module.exports.init = function (editor) {
  // This is important because it sets the asset URLs to the non-versioned URLs...
  editor.configuration.put('baseUrl', URLUtils.staticURL('/').https().toString());
};

{
  "name": "ACME Custom Editor (breakout)",
  "description": "Wrapper editor around our reusable React editor app.",
  "resources": {
    "scripts": [
      "/experience/editors/com/acme/customEditorClient.js"
    ],
    "styles": []
  }
}

 'use strict';

 var URLUtils = require('dw/web/URLUtils');
 var PageMgr = require('dw/experience/PageMgr');
 var HashMap = require('dw/util/HashMap');

 /**
  * Init the ACME Custom Editor (inline)
  * @param editor
 
  * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2Fcontent%2Fb2c_commerce%2Ftopics%2Fpage_designer%2Fb2c_custom_attr_editor.html&cp=0_7_7_4
  */
 module.exports.init = function (editor) {
+  // Create a reference to the breakout custom editor
+  var breakoutEditor = PageMgr.getCustomEditor('com.acme.customEditorBreakout', new HashMap());

   // This is important because it sets the asset URLs to the non-versioned URLs...
   editor.configuration.put('baseUrl', URLUtils.staticURL('/').https().toString());

+  // Add a dependency to the configured breakout editor
+  editor.dependencies.put('customEditorBreakout', breakoutEditor);
 };

 /**
  * Events Emitted by the Custom Attribute Editor
  *
  * The vendor specified event names for the various events we emit to
  * Page Designer.
  *
  * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2Fcontent%2Fb2c_commerce%2Ftopics%2Fpage_designer%2Fb2c_custom_attr_editor.html&cp=0_7_7_4
  */
 export const SFCC_EVENT_TYPES = {
+  BREAKOUT_OPEN: 'sfcc:breakout',
+  BREAKOUT_APPLY: 'sfcc:breakoutApply',
+  BREAKOUT_CANCEL: 'sfcc:breakoutCancel',
   EDITOR_INTERACTED: 'sfcc:interacted',
   VALUE_VALID: 'sfcc:valid',
   VALUE_APPLY: 'sfcc:value'
 }

+/**
+ * BREAKOUT EDITOR
+ *
+ * This is the editor name as defined in the editor_definition files
+ * in the `app_custom_bm_extensions` cartridge.
+ *
+ * This value should match the breakout editor file name(s).
+ *
+ * @see cartridges/app_custom_bm_extensions/cartridge/experience/editors/com/acme/customEditorBreakout.js
+ */
+const SFCC_CUSTOM_EDITOR_KEY = 'customEditorBreakout';
+
+/* LocalStorage key for breakout editors */
+export const BREAKOUT_EDITOR_STORAGE_KEY = 'acme-breakout-editor-type';

 /**
  * Communicate updates to Page Designer
  *
  * @param {Object} newValue - The new/existing data value for this attribute.
  * @param {boolean} [isValid=true] - Update the current validity state of the attribute in Page Designer.
  * @param {String} validityMessage - (Optional) A message to pass to Page Designer that will render as the error message.
  */
 export const handleChangeEvent = (newValue, isValid = true, validityMessage) => {
   handleInteraction();
   handleValidity(isValid, validityMessage);
   handleUpdate(newValue);
 };

 /**
  * 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.
  */
 const handleInteraction = () => {
   window.emit({
     type: SFCC_EVENT_TYPES.EDITOR_INTERACTED
   });
 };

+/**
+ * Trigger a breakout event for the editor app.
+ *
+ * @see https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/page_designer/b2c_client_side_breakout_cae.html?resultof=%22%62%72%65%61%6b%6f%75%74%22%20
+ */
+export const handleBreakoutRequest = (title, editorType, onApply, onCancel) => {
+
+  // Before we trigger the breakout we need to set a localstorage value to
+  // communicate which editor it should be displaying in the pop-up.
+  window.localStorage.setItem(BREAKOUT_EDITOR_STORAGE_KEY, editorType);
+
+  const breakoutCloseCallback = ({ type, value }) => {
+    if (type === SFCC_EVENT_TYPES.BREAKOUT_APPLY) {
+      console.log(`Breakout editor "${editorType}" has been closed with: APPLY.`);
+      window.emit({
+        type: SFCC_EVENT_TYPES.VALUE_APPLY,
+        payload: value
+      });
+      if (onApply) {
+        onApply(value);
+      }
+    } else {
+      console.log(`Breakout editor "${editorType}" has been closed with: CANCEL/CLOSE.`);
+      if (onCancel) {
+        onCancel();
+      }
+    }
+    window.localStorage.removeItem(BREAKOUT_EDITOR_STORAGE_KEY);
+  }
+
+  // Begin the SFCC window.emit call to tell Page Designer to open the Breakout
+  // Editor
+  window.emit({
+    type: SFCC_EVENT_TYPES.BREAKOUT_OPEN,
+    payload: {
+      id: SFCC_CUSTOM_EDITOR_KEY,
+      title: title
+    }
+  }, breakoutCloseCallback);
+
+
+};

 /**
  * Indicates whether the value of the attribute is valid. Can include an error message.
  *
  * @param {boolean} validity - If the field is valid or not
  * @param {string} message - The error message passed to override the default
  */
 const handleValidity = (validity, message) => {
   window.emit({
     type: SFCC_EVENT_TYPES.VALUE_VALID,
     payload: {
       valid: validity,
       message: message
     }
   });
 };

 /**
  * The value of the attribute. Sent when the value changes inside the editor.
  * Page Designer requires that the value be a plain JavaScript object.
  *
  * Please note: This event will mark the sidebar as having changed, clicking save
  * on the sidebar will trigger a rerender of the editor.
  *
  * @param {object} newValue - The new value to be passed to SFCC.
  */
 const handleUpdate = (newValue) => {
   window.emit({
     type: SFCC_EVENT_TYPES.VALUE_APPLY,
     payload: newValue
   });
 };

export const EditorWrapper = ({definition}) => {

  const {editorId} = useParams();

  const {config} = definition;

  if (!editorId || !availableEditors[editorId]) {
    return <ErrorPage />
  }

  const EditorComponent = availableEditors[editorId];
  const isBreakoutEditor = !config.editorType;

  return (
    <EditorComponent
      isBreakoutEditor={isBreakoutEditor}
      editorType={config.editorType}
      onChange={handleChangeEvent} // Our API client method
      onTriggerBreakoutEditor={handleBreakoutRequest}
      originalValue={definition.originalValue}
      {...config}
    />
  )
}

// Grab the window object we set in customEditorClient.js.
const definition = window.acme;

// The inline scenario this value will be what we add to our component editor config
// The breakout scenario this is undefined.
let requestedRoute = definition.route;

// Check to see if we have a value in LocalStorage.
const editorTypeFromStorage = window.localStorage.getItem('example-ls-key');

// If the route is undefined AND we have a localstorage key, we're probably in breakout mode.
if(requestedRoute === '/editor/undefined' && editorTypeFromStorage) {
  requestedRoute = `/editor/${editorTypeFromStorage}`;
}

<form>
  {/* register your input into the hook by invoking the "register" function */}
  <input defaultValue="test" {...register("example")} />

  {/* include validation with required or other standard HTML validation rules */}
  <input {...register("exampleRequired", { required: true })} />
  {/* errors will return when field validation fails  */}
  {errors.exampleRequired && <span>This field is required</span>}

  <button onClick={handleSubmit(onSubmit, onError)}>Submit</button>
</form>