Support Article - PWA Content Integration Guide

Introduction

This article describes how to create and manage content using Intershop Commerce Management and integrate it into the Intershop Progressive Web App.

All steps are based on PWA 3.1, but are also valid for newer versions. Some of the features such as the category and product includes require at least PWA 2.1. This article will be extended in the future, with the release of new PWA versions.

References

RSS CMS vs PWA CMS

There are a few differences between the standard CMS of the responsive storefront and the CMS used in the PWA. One of them being that the standard CMS heavily relies on pages and their respective slots to display content while the PWA CMS makes use of Includes and View Contexts which are referenced in Angular files.

Adjustments to the Content of the Homepage

The Standard "Homepage Content" Include 

It is possible to assign or unassign components to or from specific includes via the ICM back office. To do so, open a Progressive Web App application and switch to Content | Includes.

For example, you can find the include Homepage Content which gathers multiple component containers. These hold the components which are going to be displayed in the storefront.

Example: Include - Homepage Content (include.homepage.content.pagelet2-Include):


The include "Homepage Content" (include.homepage.content.pagelet2-Include) inherits the assignment of all component containers which are assigned to the container component "PWA Homepage Grid" (pwa_homepage_grid).


Example: Component container assignment to "Include - PWA Homepage Grid" (pwa_homepage_grid):

Example: Component assignment to component "Container - PWA Featured Products" (pwa_featured_products) to "PWA Homepage Grid - Full Width Multiple Slot" (pwa_homepage_grid5):


The following component groups are available:

NameAssigned Components by DefaultSpecificationsRepresentation in the Storefront
PWA Homepage Grid - Full Width Single Slot

PWA Homepage Carousel

  • One available slot for components
  • The component takes up the whole width of the storefront

PWA Homepage Grid - Third Width Single Slot - left

PWA Homepage Grid - Third Width Single Slot - middle

PWA Homepage Grid - Third Width Single Slot - right

PWA Cat Teaser 1

PWA Cat Teaser 2

PWA Cat Teaser 3

  • One available slot for components (one for each: left, middle, and right)
  • Each component takes up one third of the width of the storefront

PWA Homepage Grid - Full Width Multiple SlotPWA Featured Products
  • Multiple available slots for components
  • Each component takes up the whole width of the storefront

Assign / Unassign Components

To assign or unassign a component in the ICM back office, click on the appropriate component group mentioned in section Standard "Homepage Content" Include and assign or unassign them in the Container Content section.

The following standard components can be assigned / unassigned:

  1. Terms & Conditions
  2. Privacy Policy
  3. PWA Homepage Carousel
  4. PWA Slider Teaser 1
  5. PWA Slider Teaser 2
  6. PWA Featured Products
  7. PWA Cat Teaser 1
  8. PWA Cat Teaser 2
  9. PWA Cat Teaser 3
  10. Helpdesk - Start

It is also possible to add components to other includes like Content Include 01 and to use them instead.

Create New Components

It is possible to create further components with the available templates for new components by clicking the New button.

The following standard templates are available by default:

  1. Carousel
  2. Container
  3. Enhanced Image Teaser
  4. Free Style HTML
  5. Image
  6. Product List (Category)
  7. Product List (Filter)
  8. Product List (Manual)
  9. Text
  10. Video

However, it is also possible to create own templates by switching to the ICM menu Content | Component Templates | New. Furthermore, components can also be created without using a template at all.

Adjustments to Category Pages, Family Pages and Product Pages

Adjustments via Already Existing View Contexts

It is possible to use already existing view contexts from the back office in the Intershop PWA storefront.

To do this, go to the ICM back office, open a PWA application channel and switch to Content | View Contexts.

The following table shows the view contexts that are available by default:

View ContextStandard Reference Location in the PWA Source Code

Representation in the Storefront

Category Base Marketing Bottom\src\app\pages\category\category-categories\category-categories.component.html
Category Base Marketing Top\src\app\pages\category\category-categories\category-categories.component.html
Category Content Marketing Bottom\src\app\pages\category\category-categories\category-categories.component.html
Category Content Marketing Top\src\app\pages\category\category-categories\category-categories.component.html
Category Navigation Panel Marketing

\src\app\pages\category\category-categories\category-categories.component.html

Family Base Marketing Top\src\app\pages\category\category-products\category-products.component.html

Family Base Marketing Bottom\src\app\pages\category\category-products\category-products.component.html
Family Content Marketing Bottom\src\app\pages\category\category-products\category-products.component.html
Family Content Marketing Top\src\app\pages\category\category-products\category-products.component.html
Family Navigation Panel Marketing\src\app\pages\category\category-products\category-products.component.html
Product Base Marketing Bottom\src\app\pages\product\product-page.component.html
Product Base Marketing Top\src\app\pages\product\product-page.component.html
Product Content Marketing Bottom\src\app\pages\product\product-page.component.html
Product Content Marketing Top\src\app\pages\product\product-page.component.html
Product Info Marketing

\src\app\pages\product\product-detail\product-detail.component.html

These view contexts can then be assigned either to category pages, family pages or product pages. In this way, the configured content is displayed for the corresponding business object in the PWA storefront.

To give a simple example, the following section describes how to use the view context Category Base Marketing Top for a category page:

  1. Open a PWA application channel in the ICM back office and go to Catalogs | Catalogs.
  2. Open the catalog (e.g.: Specials), click on View Properties and switch to the Content tab.

    From here, the existing view contexts can be used.
  3. Click on New under Includes, select the view context Category Base Marketing Top and click on OK.

    After opening the Category Include it is possible to assign new or already existing components to the view context.
  4. Example: one option would be to create a new component with the Image template and to apply an advertising banner to the category page.

    After these changes, the specified content is displayed in the PWA storefront:


Adjustments via New View Contexts

Instead of using already existing view contexts, it is also possible to create new view contexts of the type Category Include or Product Include, which can then also be used in the Intershop PWA.

The Category Include view context can be displayed for category and family pages while the Product Include view context can be displayed for product pages.

The next sections show how to create and use a view context of the type Category Include and also of the type Product Include.

Create and Use a New View Context of the Type "Category Include"

  1. Open a Progressive Web App application in the ICM back office, go to Content | View Contexts, and click New.
  2. Enter a Name, ID and Category Include as the Type of the view context:
  3. To assign the created view context to specific categories, go to Catalogs | Catalogs and open a category (e.g.: Specials).
  4. Click View Properties and switch to the Content tab.
  5. Click New below Includes, select the created view context of the type Category Include and click OK.

    After opening the Category Include it is possible to assign new or already existing components to the view context.
    For example, one option would be to create a new component with the Image template and to apply an advertising banner to the category page.
  6. To display this view context for all specified categories, open the PWA source code, go to the category-page.component.html file and add an <ish-content-viewcontext> element in the following way:

    <ng-container *ngIf="category$ | async as category">
    [...]
    	<ish-content-viewcontext
          *ngIf="category.categoryRef"
          viewContextId="ViewContext"
          [callParameters]="{ Category: category.categoryRef }"
    	></ish-content-viewcontext>
    [...]
    </ng-container>

    Please make sure to enter your specific "viewContextId".

  7. To display a view context on previously specified family pages, add an <ish-content-viewcontext> element in the category-products.component.html file in the following way:

    [...]
    <ish-content-viewcontext
    	*ngIf="category.categoryRef"
        viewContextId="Test12345"
        [callParameters]="{ Category: category.categoryRef }"
    ></ish-content-viewcontext>
    [...]

    After these changes, the specified content is displayed in the PWA storefront for all specified categories.

Create and Use a New View Context of the Type "Product Include"

  1. Open a Progressive Web App application in the ICM back office, go to Content | View Contexts, and click New.
  2. Enter a Name, ID and Product Include as the Type of the view context.
  3. To assign this view context to specific products, go to Catalogs | Products and open a product (e.g.: Microsoft Surface Hub).
  4. Switch to the Content tab.
  5. Click on New below Includes, select the created view context of the type Product Include and click OK.

    After opening the Product Include it is possible to assign new or already existing components to the view context.
    For example, one option would be to create a new component with the Image template and to apply an advertising banner to the product page.
  6. To display this view context for all specified products, open the PWA source code, go to the product-page.component.html file and add an <ish-content-viewcontext> element in the following way:

    <div *ngIf="product$ | async as product">
    [...]
    	<ish-content-viewcontext
            viewContextId="ViewContext"
            [callParameters]="{ Product: product.sku }"
        ></ish-content-viewcontext>
    [...]
    </div>

    Please make sure to enter your specific "viewContextId".

    After these changes, the specified content is displayed in the PWA storefront.


Use Custom Includes in the PWA Storefront

Content (from the ICM back office) can be integrated into the PWA via the <ish-content-include> element. For example, the Homepage Content include is used in the home-page.component.html file under intershop-pwa/src/app/pages/home/home-page.component.html

home-page.component.html
<ish-content-include includeId="include.homepage.content.pagelet2-Include"></ish-content-include>

In this way, it is possible to add includes with assigned components to a page in the PWA project by using the <ish-content-include> element and referencing the appropriate include via the includeId attribute.

However, when includes are to be added to the application header and footer, the <ish-lazy-content-include> element must be used instead.

<ish-lazy-content-include includeId="include.homepage.content.pagelet2-Include"></ish-lazy-content-include>

This is required since the element enables providing a lazy loading content include component that can be used within the ShellModule and therefore in the header and footer of the application.

Adjust and Use the Content of an Already Existing Include

It is possible to use already existing includes in the back office and use them in the Intershop PWA storefront. To do so, perform the following steps:

  1. In the ICM back office, switch to a PWA application and go to Content | Includes.
    There are ten already prepared content includes which can be used as a fresh include to display content in the PWA storefront.
    To provide a simple example, in the following it is described how to use a content include to display content in the footer of the PWA storefront.
  2. Open a content include (e.g.: Content Include 01), switch to the tab Components and assign a new or already existing component to it.
    In this example, a promotional banner image will be assigned to the include.
  3. Reference the include in the PWA source code.
    Therefore open the file footer.component.html under \src\app\shell\footer\footer\footer.component.html and add an <ish-lazy-content-include> element.

    <div class="footer">
        <div class="container">
    	[...]
    		<ish-lazy-content-include includeId="include.general.01.pagelet2-Include"></ish-lazy-content-include>
    	[...]
    	</div>
    </div>

    Please make sure to enter your specific includeId.

    The <ish-lazy-content-include> element is required since it enables providing a lazy loading content include component that can be used within the ShellModule and therefore in the header and footer of the application.

    After these changes, the specified content is displayed in the PWA storefront.


Create a (System-Managed) CMS Include

It is also possible to create an own system-managed CMS include via a custom project cartridge if the already existing includes are not suitable.

This example shows how to create a system-managed CMS include that can later be used to integrate content into the PWA application:

  1. Specify the (headless) application type the cartridge is assigned to, e.g., intershop.REST.

    app_sf_ext_content_cartridge/staticfiles/cartridge/components/apps-extension.component
    <?xml version="1.0" encoding="UTF-8"?>
    <components xmlns="http://www.intershop.de/component/2010">
        <fulfill requirement="selectedCartridge" value="app_sf_ext_content_cartridge" of="intershop.REST.Cartridges"/>
    </components>
    
  2. Define a new empty CMS include and reference one or more interfaces.

    app_sf_ext_content_cartridge/staticfiles/cartridge/pagelets/includes/include.ext.homepage.content.pagelet2
    <?xml version="1.0" encoding="UTF-8"?>
    <pagelet:PageletModel xmlns:pagelet="http://www.intershop.de/pagelet/2010" name="include.ext.homepage.content.pagelet2">
      <componentEntryPointDefinitions name="Include" multiplicity="ZERO_MANY" systemManaged="true">
        <callParameterInterfaces referencedName="app_sf_base_cm:interface.common.content.pagelet2-Interface"/>
        <callParameterInterfaces referencedName="app_sf_base_cm:interface.common.content.advanced.pagelet2-Interface"/>
      </componentEntryPointDefinitions>
    </pagelet:PageletModel>
    

    Interfaces are used to be able to associate components with the include. In this example, the standard interfaces interface.common.content.pagelet2-Interface and interface.common.content.advanced.pagelet2-Interface from cartridge app_sf_base_cm are used.

    If no component can be assigned to the include, check the referenced interface and its component references. Interfaces must be referenced from the component itself.

    Component Example (component.common.example.pagelet2)
    <?xml version="1.0" encoding="UTF-8"?>
    <pagelet:PageletModel xmlns:pagelet="http://www.intershop.de/pagelet/2010" name="component.common.example.pagelet2">
      <pageletDefinitions name="Component">
        <callParameterInterfaces referencedName="app_sf_responsive_cm:interface.common.content.pagelet2-Interface"/>
        <renderTemplate referencedName="component/common/Example"/>
      </pageletDefinitions>
    </pagelet:PageletModel>
    
    
  3. Add localized properties values to the CMS include.

    app_sf_ext_content_cartridge/staticfiles/cartridge/pagelets/includes/include.ext.homepage.content.properties
    #Localizable properties associated with include.ext.homepage.content.pagelet2
    ComponentEntryPoint.Include.description=Include to manage extension content of the Homepage.
    ComponentEntryPoint.Include.displaygroup=Homepage Include Ext
    ComponentEntryPoint.Include.displayname=Homepage Content Ext
    

Integration of Custom CMS Content Pages into the PWA Storefront

All pages that are delivered with the PWA sources provide the necessary functionality to operate a storefront. They follow a similar concept like system pages known from the Intershop CMS. However, it is still possible to extend the storefront by using content pages. These pages can be created and managed in the ICM back office and integrated into your PWA.

Create a New Content Page

First off all, you need to create a page. Ensure to do this inside of the Progressive Web App of your channel.

If you do not know how to create a new page, please have a look at our Video Tutorial - Content Management System (Part 1): How to Create an own Page From Scratch.

After having created the page, you need a page variant to display content.

You can fill your page variant with different content.

The Standard Page page template already provides a header and footer.

Link the Page to Your PWA

After you have created a new page and assigned a page variant with some content, you need to link it to the PWA.

The link to the page needs to be in the following format: page://Page_ID.

There are two options two link the page:

  • You can use the link in CMS components like HTML components:
  • Alternatively, you can include it directly in the PWA sources, for example, in the localization key footer.content located in .../src/assets/i18n/en_US.json
    There you need to add a href link:

    href link
    <a href=\"page://Content_Page\">Content Page</a>

Now the page is available in the PWA storefront:

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets