6. Incorporate Components into Parent Page

Overview

When the ByAllAccounts Connect Suite components are incorporated into a parent page, the 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 the Account Summary component and relay that to the Account Linking component 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 the parent page must also listen for and manage critical events issued from both components. Additionally, the required attribute (auth-context) 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 table describes the attributes for the Account Linking and the Account Summary components. The only required attribute for the components is auth-context.

Any of these attributes can be set (and reset) at any time but translate-file-path, override-css-file, and ui-config-file (for Account Linking) typically do not change during the lifetime of a parent page. An example of when auth-context might be reset during the lifetime of a parent page would be handling of an authorization expiring.

Instructions

Instantiating ByAllAccounts Connect Suite into your parent page

In a typical usage scenario of the ByAllAccounts Connect Suite, the Account Summary component is displayed first and occupies a section on the parent page.

When the user performs an action in the Account Summary component, the Account Linking component is launched in a modal dialog where the user steps through the wizard flow to perform the associated operation.

When the user completes the operation in the Account Linking component, the user exits that component, the dialog is dismissed, and control is returned back to the Account Summary component.

These interactions between the Account Summary and Account Linking components can repeat multiple times during a user session, and at each time the Account Linking component needs to be launched in the dialog and then dismissed.

This launching of the Account Linking component can potentially be an expensive and lengthy operation as it involves network activity to load the component’s JS bundles and to establish the session. To make this behavior as performant and smooth as possible, and to provide a good user experience to the user, it is recommended that both the Account Summary and the Account Linking components be preloaded and instantiated 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.

The following code sample shows how to instantiate the components as recommended, including setting the auth-context attribute for each component for authentication purposes.
Note: Your parent page must additionally listen for and manage the critical events which are described in 7. Manage Critical Events.

The following code example shows how to instantiate the component. You can also refer to this recipe which describes the code for instantiating the components.

<!-- 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.settAttribute(‘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>

Example launching Account Summary

This section shows a code example for launching Account Summary with all applicable attributes. This sample integration code:

• 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 are available to:

• Customize the user interface: translate-file-path, override-css-file, custom-fonts
  These attributes typically do not change during the lifetime of the parent page. We recommend setting these attributes first.
• Provide 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 the auth-context attribute.

See Attributes for detailed information about attributes.

In the following sample code for launching Account Summary with all applicable attributes, replace hostname with your host name for those files. You can also refer to the recipe for launching Account Summary.

<!-- 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>

Example Launching Account Linking

This section shows a code example for launching Account Linking with all applicable required attributes. This sample integration code:

• 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 are available to:

• Customize the user interface: ui-config-file, translate-file-path, override-css-file, custom-fonts
  These attributes typically do not change during the lifetime of the parent page. We recommend setting these attributes first.
• Provide 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 the auth-context attribute, you must then reset the route attribute.

See Attributes for detailed information about attributes.

In this sample code for launching Account Linking with all applicable required attributes, replace hostname with your host name for those files. You can also refer to the Recipe for launching Account Linking.

<!-- 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>