We provide a location strategy for Angular called WebComponentLocationStrategy that uses a special syntax to allow web component routing that is reflected in the URL without interfering with the hosting app's routing - assuming that it is not using hash based routing. This location strategy is the default for TALY-generated web components.
To use this location strategy in your web component you need to add a provider for LocationStrategy that points to the WebComponentLocationStrategy class. This location strategy relies on a provider for the InjectionToken WEB_COMPONENT_ID so you also need to provide a value for that. Both the WebComponentLocationStrategy as well as the injection token WEB_COMPONENT_ID can be imported from @allianz/taly-common/web-component.
Example:
import { LocationStrategy } from '@angular/common';
import { WebComponentLocationStrategy, WEB_COMPONENT_ID } from '@allianz/taly-common/web-components';
@NgModule({
// ...
providers: [
{ provide: WEB_COMPONENT_ID, useValue: 'my-web-component' },
{ provide: LocationStrategy, useClass: WebComponentLocationStrategy }
]
})
// ...Any generated web component uses the WebComponentLocationStrategy by default.
Given a WEB_COMPONENT_ID of "my-web-component" and a web component internal route of /internalPath this location strategy will produce paths like this:
.../some/host/path/#(my-web-component:/internalPath)Given there are multiple web components on the same page that use this location strategy they will neatly live alongside each other and produce paths like so:
.../path/#(my-web-component:/internalPath,other-web-component:/other/path)⚠️ This location strategy changes the hash of the URL.
This location strategy works fine if there are multiple web components on the same page that use this location strategy.
Scenarios exist where it might not be a good idea to take control over or change the URL's hash. This is a (probably incomplete) list of scenarios where you would want to avoid using this location strategy:
Fragment scrolling
The WebComponentLocationStrategy is not meant to be used on pages that use fragments as part of their URLs. If a page some/path#overview contains a web component that uses this location strategy it will lead to paths like some/path#overview(some-web-component:/some-path). This new URL will break the browser-built-in fragment-scrolling.
Hash based routing in host application
If the host application of your web component is using a hash based location strategy (like Angular's built-in HashLocationStrategy) then the WebComponentLocationStrategy cannot be used since it would interfere with the host application's routing. In this case it is advised to use a location strategy for your web component that doesn't change the URL at all. Another solution would be to ask the host application to change to a path based location strategy.
Someone else owns the hash
If the web component that uses the WebComponentLocationStrategy lives on the same page with another element that wants to take control over the hash (e.g. another web component that uses a different strategy or some other element/script) then they might get in each other's way. In this case it's better to use a location strategy in your web component that does not change the URL at all.
Apart from the WebComponentLocationStrategy, we also provide another location strategy called NoopLocationStrategy that does not change the URL at all. This is useful if you find that the previous location strategy leads to conflicts with the host application of your web component.
To use this location strategy in your web component you need to add a provider for LocationStrategy that points to the NoopLocationStrategy class. The NoopLocationStrategy is available via @allianz/taly-common/web-component.
Example:
import { LocationStrategy } from '@angular/common';
import { NoopLocationStrategy } from '@allianz/taly-common/web-components';
@NgModule({
// ...
providers: [
{ provide: LocationStrategy, useClass: NoopLocationStrategy }
]
})
// ...If you want to use the NoopLocationStrategy you can pass the flag --use-noop-location-strategy in your generator call. Alternatively, you can also set the useNoopLocationStrategy flag in the executor options of your project.json:
{
"...": "...",
"options": {
"useNoopLocationStrategy": true
}
}💡 This feature is only supported for Retail journeys.
TALY provides the ability to link back to another page from two different places throughout the journey. It is possible to display a back link in the upper part of the TALY Frame stage and/or to navigate to the same URL when clicking on the "Next" button on the last page of the journey. This feature is mostly intended to navigate back to an external link from which the journey was started, but it could be used for any other purpose.
For the back link in the TALY Frame stage, the link can be disabled on the page level, thanks to the hideBackLink flag inside the page configuration for the journey:
// Page configuration
{
"id": "my-page-c",
"blocks": [{ "...": "..." }],
"title": {
"headline": "Page C is good",
"showAsStage": true,
"subline": "Really good",
"hideBackLink": true
}
}Additionally, and likewise only applicably to the stage back link, a PFE Service Activator can be executed when clicking on the back link, before redirecting. TALY will prevent the redirect if the Service Activator call fails. Here is an example of how to configure this in your journey configuration:
{
"...": "...",
"frame": {
"stage": {
"backLink": {
"onClickServiceActivator": "users"
}
},
"...": "..."
},
"...": "..."
}For this feature to work with AEM pages, the back link configuration needs to be added to the customconfiguration object via the AEM user interface. More precisely, a key called backLinkConfig needs to be set to a value that implements the BackLinkConfiguration interface defined in TALY. This is an example of this value (note the use of double quotes preceded by a backslash, this is required for the data to be extracted from customconfiguration in runtime).
{\"backLinks\": [ {\"path\": \"dashboard\", \"stageLinklabel\": \"Go Back to Dashboard\", \"nextButtonLabel\": \"Go to Dashboard\"}, {\"path\": \"localhost:4000\", \"stageLinkLabel\": \"Back to example app\"} ], \"default\": {\"path\": \"https://allianz.com\", \"stageLinkLabel\": \"Default\" }}TALY provides an adapter (BackLinkAemAdapterService) that reads the data from the root element and processes it. The functionality is based on the value of document.referrer. In a nutshell, it does the following:
backLinks via customconfiguration, that item is used for the back link.backLinks, if provided it takes the default entry from customconfiguration.stageLinkLabel field, the back link will not be displayed in the TALY Frame stage. The same applies to the "Next" button on the last page of the journey. If the field nextButtonLabel is not provided, the back link feature is disabled for that button, and the button will be hidden unless it is explicitly configured to be shown in the PFE configuration.Web components need to add a couple of providers to integrate this feature. First, they need to provide the WEB_COMPONENT_ID injection token to contain the web component's tag name. And second, an implementation of the BackLinkAdapterService service, either the TALY's BackLinkAemAdapterService that leverages the AEM integration, or any other custom implementation that provides a different integration. Example:
import {
BackLinkAdapterService,
BackLinkAemAdapterService,
WEB_COMPONENT_ID
} from '@allianz/taly-common/web-components';
@NgModule({
"...": "...",
providers: [
"...": "...",
{ provide: WEB_COMPONENT_ID, useValue: 'my-taly-app' },
{
provide: BackLinkAdapterService,
useClass: BackLinkAemAdapterService
}
]
})
export class MyTalyIntegrationModule {}The host application needs to pass the configuration data to the web component in a way that allows the corresponding adapter to read it. An example is the AEM integration, explained in the previous section.
TALY-generated Retail web components include the AEM Adapter. The back link feature will therefore be automatically available, as long as those web components are integrated into the host application following the AEM integration.
TALY-based customer journey web components provide the possibility to get and restore their state from outside.
The current PFE state can be retrieved via the getState() method provided in the web component element.
For example:
const webComponent = // get the element reference from the DOM, for example by the tag name
const currentState = webComponent.getState();The host application can provide an initial state for the customer journey. This state is then restored when the customer journey starts up and the journey continues where it left off.
The journey can be initialized with a state like this:
<my-taly-app initial-state='{"state": "value"}'> </my-taly-app>For Angular hosts, the initial state can alternatively be passed to the journey via dynamic binding:
// Component class
// Imports and component decorator...
export class AppComponent {
webComponentInitialState = '{ "state": "value" }';
}<!-- Component template -->
<my-taly-app [initialState]="webComponentInitialState"> </my-taly-app>In this case, the bound property can be a JSON string or a promise that eventually resolves to a JSON string.
💡 Keep in mind that this feature is incompatible with other PFE state initialization strategies, like web component inputs added to the journey configuration or PFE state updates performed by TALY plugin modules during their initialization. This is the intended behavior, since the initial state feature is meant to fully restore the PFE state from a previous session, and no other PFE state initializations should happen in parallel to that.