6. Incorporate Components into Parent Page

Overview

When the Account Summary and Account Linking components are incorporated into a parent page, Account Summary is visible and acts as the primary controlling entity for the suite. The parent page must monitor for the accountSetup event issued by Account Summary and relay it to Account Linking to tell it which workflow to start when it exposes the component. That's the only information the parent page needs to relay between the two components, but it must also listen for and manage critical events issued from both components.

Additionally, the required auth-context attribute must be set for each component to manage authorization. Optionally, other attributes may be set for customizations.

This section includes:

• Descriptions of all attributes for the components
• Code for instantiating the components in your parent page
• Code samples for each component, showing all applicable attributes.

Attributes

The following section describes the attributes for the Account Linking and the Account Summary components.

Required attribute: auth-context

The auth-context attribute must be set at instantiation for the integration to function correctly.

• Applies to: Both components
• Description: Authenticates the user. Must be reset whenever authentication changes (for example, after a session timeout).
• Accepted values:
  • { jsessionId: <jsessionIdValue>, csrfToken: <csrfTokenValue> } — sets the authenticated session
  • {} — clears authentication and prevents further use of the component

Workflow control attribute: route

The route attribute is set during the integration to control Account Linking workflows.

• Applies to: Account Linking only
• Description: Tells Account Linking which workflow to open. Set this attribute using the detail string from the Account Summary accountSetup event (see step 7).
• Must be set afterauth-context — otherwise a badAuthentication event will fire.
• Account Linking notifies the parent page when the workflow completes.

Customization attributes

These attributes are optional and customize the appearance and behavior of the components. translate-file-path, override-css-file, and ui-config-file (for Account Linking) typically do not change during the lifetime of a parent page.

Instructions

1. Instantiate the components into your parent page

The typical interaction flow:

• Account Summary is displayed first and occupies a section on the parent page.
• When the user performs an action in Account Summary, Account Linking is launched in a modal dialog where the user steps through the wizard flow.
• When the user completes the operation, they exit Account Linking, the dialog is dismissed, and control returns to Account Summary.
• These interactions can repeat multiple times during a user session.

Why preloading is recommended:

Launching Account Linking on demand can be an expensive and lengthy operation — it involves network activity to load the component's JS bundles and establish the session. To keep this performant and provide a good user experience, we recommend preloading and instantiating both components at the start of the parent application session, when the user logs in. The preloaded Account Linking component should then be placed in the modal dialog, ready to be used but kept hidden until it is needed.

Code sample:

To learn how to instantiate the components as recommended — including setting the auth-context attribute for authentication — use the recipe for a step-by-step walkthrough or expand the accordion to view the full code in one block.

<!-- Load the main JavaScript bundle file of the Account Summary component -->
<script src="./mstar-aggregation-consumer-accountsummary.js"></script>
<!-- Instantiate Account Summary (summaryCE) component -->
<script>
summaryCE = document.createElement("mstar-aggregation-consumer-accountsummary");
summaryCE.setAttribute("auth-context", JSON.stringify(
{ jsessionId: "<jsession id>",
  csrfToken: "<csrf token>"
}));

// Add an event listener that listens to accountSetup events fired by the Account Summary (summaryCE) component, and when fired, display the Account Linking (setupCE) component
summaryCE.addEventListener('accountSetup', (e) => {
// Set the route attribute of the Account Linking (setupCE) component using the value passed in the event
setupCE.setAttribute('route', e.detail);
// Show the Account Linking (setupCE) modal dialog
document.getElementById('dialog').showModal();
});

content.appendChild(summaryCE);
</script>

<!-- Preload the main JavaScript bundle file of the Account Linking (setupCE) component -->
<script src="./mstar-aggregation-consumer-accountsetup.js"></script>
<!-- Instantiate Account Linking (setupCE) component and keep it hidden -->
<script>
setupCE = document.createElement("mstar-aggregation-consumer-accountsetup");
setupCE.setAttribute("auth-context", JSON.stringify(
{ jsessionId: "<jsession id>",
  csrfToken: "<csrf token>"
}));

// Add an event listener that listens to userExit events fired by the Account Linking (setupCE) component, and when fired, hide the modal dialog
setupCE.addEventListener('userExit', (e) => {
  // Hide the Account Linking (setupCE) modal dialog
  document.getElementById('dialog').close();
});

// Add the Account Linking (setupCE) component to the dialog element and keep it hidden
content = document.getElementById('dialog');
content.appendChild(setupCE);
</script>

2. Example launching Account Summary

What this sample demonstrates:

• Loads the Account Summary component
• Instantiates the component in the page
• Sets all common attributes including the required auth-context attribute to provide authentication
• Makes Account Summary visible in the page

Attributes used:

• For UI customization: translate-file-path, override-css-file, custom-fonts. These typically do not change during the lifetime of the parent page. We recommend setting them first.
• For authentication: auth-context. Authentication can change during the life of the parent page. When authentication expires or a new user is authenticated, you need to reset auth-context.

Code sample:

To launch Account Summary with all applicable attributes — replacing hostname with your host name where shown — use the recipe for a step-by-step walkthrough or expand to view the full code in one block.

<!-- Load the main JavaScript bundle file of the Account Summary component -->
<script src="./mstar-aggregation-consumer-accountsummary.js"></script>
<script>
mstarWebComp = document.createElement("mstar-aggregation-consumer-accountsummary");
mstarWebComp.setAttribute("ui-config-file", "https://hostname/customassets/config/ui-config.json");
mstarWebComp.setAttribute("translate-file-path", "https://hostname/customassets/i18n/");
mstarWebComp.setAttribute("override-css-file", "https://hostname/customassets/css/corporatestyle.css");
mstarWebComp.setAttribute("custom-fonts", "https://fonts.googleapis.com/css?family=Lobster");
mstarWebComp.setAttribute("auth-context", JSON.stringify(
  { jsessionId: "212764322EB9DBEBED880425DE3216EB.s1a",
    csrfToken: "DBC63BDE361C192B3CEF641B4C551DD8AC27B4A0276E91"
  }));
content.appendChild(mstarWebComp);
</script>

3. Example launching Account Linking

What this sample demonstrates:

• Loads the Account Linking component
• Listens and instantiates the component in the page
• Sets all common attributes including the required auth-context attribute to provide authentication
• Makes Account Linking visible in the page

Attributes used:

• For UI customization: ui-config-file, translate-file-path, override-css-file, custom-fonts. These typically do not change during the lifetime of the parent page. We recommend setting them first.
• For authentication: auth-context. Authentication can change during the life of the parent page when authentication expires or a new user is authenticated. If you reset auth-context, you must then reset route.

Code sample:

To launch Account Linking with all applicable required attributes — replacing hostname with your host name where shown — use the recipe for a step-by-step walkthrough or expand to view the full code in one block.

<!-- Load the main JavaScript bundle file of the Account Linking component -->
<script src="./mstar-aggregation-consumer-accountsetup.js"></script>
<script>
  // This event listener listens to accountSetup events fired by the Account Summary component, and when fired it launches the Account Linking component
  summaryCE.addEventListener('accountSetup', (e) => {
    mstarWebComp = document.createElement("mstar-aggregation-consumer-accountsetup");
    // Set attributes
    mstarWebComp.setAttribute("ui-config-file", "https://hostname/customassets/config/ui-config.json");
    mstarWebComp.setAttribute("translate-file-path", "https://hostname/customassets/i18n/");
    mstarWebComp.setAttribute("override-css-file", "https://hostname/customassets/css/corporatestyle.css");
    mstarWebComp.setAttribute("custom-fonts", "https://fonts.googleapis.com/css?family=Lobster");
    // Pass in the auth context of the logged in user to the mstar component
    mstarWebComp.setAttribute("auth-context", JSON.stringify(
      { jsessionId: "212764322EB9DBEBED880425DE3216EB.s1a",
        csrfToken: "DBC63BDE361C192B3CEF641B4C551DD8AC27B4A0276E91"
      }));
    content.appendChild(mstarWebComp);
  });
</script>

👍

Success Criteria

Upon successful incorporation of the components, you will have:

• Both components instantiated in your parent page with valid auth-context values
• The parent page listening for the accountSetup event from Account Summary and relaying it to Account Linking via the route attribute
• The parent page prepared to monitor for and handle critical events from both components (covered in the next step)