Skip to content

Latest commit

 

History

History
192 lines (151 loc) · 5.76 KB

brx-spartacus-integrations.md

File metadata and controls

192 lines (151 loc) · 5.76 KB

Integration examples

Adding a brX container to a spartacus page

Spartacus outlets allow for extra angular components / DOM to be added at certain points in the page. This works nicely with the components and directives provided by the Bloomreach NG SDK. The below example showcases how one can 'inject' a brX component into a Spartacus page. It's using the cx-header outlet to output a container and its container-items right after the header.

In general we suggest only using the Software-driven outlets because we want to enable users to use brX and those will not be able to use Cms-driven outlets.

This way it is also possible to output brX containers on Product pages normally generated by SAP.

Since this is the root template it would try and render this 'main' component on every page load. Therefore a Dev should make sure this main component is present in the channel layout definition set up via the Site Dev API and match every page defined in SAP with some channel route (that could be a wildcard matcher).

Example wildcard channel route that uses the 'content' layout:

{
  "name": "_any_",
  "layout": "content",
  "relativeContentPath": "pages/${1}"
}

Example 'content' channel layout that contains 'main' component:

{
  "name": "content",
  "type": "page",
  "extends": "base",
  "components": [
    {
      "name": "main",
      "components": [
        {
          "name": "container",
          "xtype": "hst.nomarkup",
          "type": "managed"
        }
      ],
      "type": "static"
    }
  ]
}

Example app-root template that uses an outlet to output the 'main' container after the cx-header:

<br-page
  [configuration]="configuration"
  [mapping]="mapping"
  (state)="setVisitor($event)"
>
  <ng-template let-page="page">
    <cx-storefront></cx-storefront>

    <ng-template cxOutletRef="cx-header" [cxOutletPos]="outletPosition.AFTER">
      <ng-container brComponent="main"></ng-container>
    </ng-template>
  </ng-template>
</br-page>

Editing spartacus component properties in brX

Many Spartacus component get their data from an injected value like CmsComponentData. Utilizing Angular DI and viewContainerRef we can dynamically replace that injected value with data from the brX platform.

To get this data one would have to define a brX component that defines the properties to be edited via the Site Dev API (TODO: insert link here). For example the SpartacusBanner component can be defined as: [insert json blob here]

{
  "id": "sample-group/spartacus-banner",
  "extends": "base/component",
  "ctype": "SpartacusBanner",
  "label": "SpartacusBanner",
  "parameters": [
    {
      "name": "title",
      "valueType": "string",
      "required": true
    },
    {
      "name": "content",
      "valueType": "string"
    }
  ]
}

The values of these properties can then be passed to the CmsComponentData provider to that SpartacusBanner.

renderWrappedBanner(): void {
    const componentFactory = this.componentFactoryResolver.resolveComponentFactory(BannerComponent);
    const viewContainerRef = this.wrappedComponent.viewContainerRef;
    viewContainerRef.clear();

    const componentProperties: CmsBannerComponent = {
      // getting the component properties from brX and setting them on CmsComponentData
      headline: this.data.title,
      content: this.page.rewriteLinks(this.data.content.value),
      media: {
        url: this.image.getOriginal().getUrl(),
      }
    };

    const componentInjector = Injector.create({
      providers: [
        { provide: CmsComponentData, useValue: { data$: of(componentProperties) } },
      ]
    });

    viewContainerRef.createComponent<BannerComponent>(componentFactory, 0, componentInjector);
  }

Routing

  1. Brx pages without Spartacus components
  2. SAP pages without Brx components
  3. Spartacus and Brx components at one page

1. Brx pages without Spartacus components

Steps:

  • Create a page called '/news' in Channel manager
  • Create a route with the same path as in Channel manager. 
    const routes: Routes = [{ path: 'news', component: NewsPageComponent }];
RouterModule.forRoot(routes, {

There is might be an alternative option to load some routes from backend without spartacus components link

2. SAP pages without Brx components

Steps:

  • Create a page in SAP. The page shouldn't be match with any other pages in Channel manager
  • Handle 404 error that comes from PMA. (Page doesn't exist in Channel manger)

There are 3 options to handle 404 error.

  • Handle the error using HttpGlobalInterceptor.
  • Handle the error using GlobalHandleError.
  • Handle the error using httpError event handler on br-page component.
  <br-page (httpError)="onBrxHttpError($event)" ...></br-page>

3. Spartacus and Brx components at one page

Steps:

  • Create a page in SAP
  • Create a page in Channel manager. The pages should be matched by url.

The user should be able to observe both components on the specified URL.

Connector + Adapter + Converter

The above methods all have the downside that a business user might still have to deal with SmartEdit to some point depending on how far the integration has wrapped all the Spartacus components. The best way forward to fully migrate a business user from Smart Edit to brX Saas is to write a connector and adapter (and possibly a converter) for the CMS pages as described here.

The implementation of the default CmsPageAdapter, CmsPageNormalizer and CmsComponentAdapter can be found here.