feat: Add decoration handler for handling fragment decoration

README.md

@@ -168,6 +168,14 @@ runEager.call(document, {
   // See more details on the dedicated Experiments page linked below
   experimentsMetaTagPrefix: 'experiment',
   experimentsQueryParameter: 'experiment',
+
+  /* Fragment experiment needs redecoration */
+  // See more details below
+  decorationFunction: (el) => {
+    /* handle custom decoration here, for example: */
+    buildBlock(el);
+    decorateBlock(el);
+  }
 });
 ```
 
@@ -176,6 +184,13 @@ For detailed implementation instructions on the different features, please read
 - [Campaigns](/documentation/campaigns.md)
 - [Experiments](/documentation/experiments.md)
 
+**Cases of passing `decorationFunction`**
+Fragment replacement is handled by async observer, which may execute before or after default decoration complete. So, you need to provide a decoration method to redecorate. There are several common cases:
+1. Have a selector for an element inside a block and the block needs to be redecorated => sample code above
+2. Have a `.block` selector and  need to redecorate => switch block status to `"loading"` and call `loadBlock(el)`
+3. Have a `.section` selector and need to redecorate => call `decorateBlocks(el)`
+4. Have a `main` selector and need to redecorate => call `decorateMain(el)`
+
 ## Extensibility & integrations
 
 If you need to further integrate the experimentation plugin with custom analytics reporting or other 3rd-party libraries, you can listen for the `aem:experimentation` event:

src/index.js

@@ -43,6 +43,9 @@ export const DEFAULT_OPTIONS = {
   // Experimentation related properties
   experimentsMetaTagPrefix: 'experiment',
   experimentsQueryParameter: 'experiment',
+
+  // Redecoration function for fragments
+  decorateFunction: () => {},
 };
 
 /**
@@ -436,6 +439,8 @@ function watchMutationsAndApplyFragments(
       if (url && new URL(url, window.location.origin).pathname !== window.location.pathname) {
         // eslint-disable-next-line no-await-in-loop
         res = await replaceInner(new URL(url, window.location.origin).pathname, el, entry.selector);
+        // eslint-disable-next-line no-await-in-loop
+        await pluginOptions.decorateFunction(el);
       } else {
         res = url;
       }