Note
This document is related to the Responsive Starter Store.
Starting from Intershop Commerce Management 11.0, the Responsive Starter Store is deprecated and replaced by the Intershop Progressive Web App.
Introduction
When creating a new consumer channel or a new consumer storefront application (by default) it contains no content. Very likely, leaving the user of Design View or storefront preview with a non-functioning, empty application. Browsing or manage content becomes impossible, provided that the storefront application is bound to use Intershop's content management system. A customer who visits the new shop of such a live system is likely to see this picture:
This concept describes the white label store (also known as White Store demo content) feature that delivers all objects necessary for a functional storefront application. The concept outlines how to customize such a storefront. It answers questions like what is needed to do so and about the basic nature of the white label store. The intended target audience of this concept are developers with knowledge about Intershop's content management.
Preparation
In principal, the white label store just consists of a CMS import archive. This archive contains XML formatted content management objects that become database objects by a standard import process. White label store content is used for new channel or application objects only (later referred to as unit). Its only intention is to decrease the effort for a storefront setup to show a fully functional, yet CMS managed, storefront application. The following diagram gives an overview about the steps involved in creating a white label driven web store.
Create New Unit
The organization manager creates and names a new business unit. This can either be a new sales channel or a new application within a sales channel.
A new storefront application is automatically created along with creating a sales channel.
White Store Content Archive Is Searched
A configuration value is searched by some definite naming scheme:
# Naming scheme for channel white label content whitestore.democontent.sourcedomain = <source unit name> # Naming scheme for application whitestore.democontent.sourcedomain.<ApplicationType-ID> = <source unit name>
Depending on the actual unit that is created (sales channel or application) the system tries to find a source unit name. That name must point to an already existing domain of the system, e.g., PrimeTech-PrimeTechSpecials or PrimeTech-PrimeTechSpecials-b2c-web-shop when using Intershop's standard demo scenario. The white label store preparation is not limited to PrimeTech demo scenario. As a matter of fact, that source unit name can point to any existing domain other than PrimeTech. The file whitestorecontent.properties is located in cartridge sld_ch_consumer_plugin. In case you want to give different source unit values, see section Customization & Production.
With the domain object found, the impex (as in import/export) source directory is searched for a directory named whitestore. If the system is installed with standard demo data, the resulting path could be $IS_SHARE\sites\PrimeTech-PrimeTechSpecials-Site\units\PrimeTech-PrimeTechSpecials-b2c-web-shop\impex\src\whitestore . In that case above properties file contains a setting like this: whitestore.democontent.sourcedomain.intershop.B2CWebShop=PrimeTech-PrimeTechSpecials-b2c-web-shop
Archive Is Copied and Prepared for New Unit
If a content archive is found at the given place (source unit of shared file system) the system creates a ZIP compressed file from the contents of directory whitestore. The *.zip file is placed in the import source directory of the newly created unit, e.g., $IS_SHARE\sites\YourOrganization-YourChannel-Site\units\<NEW_UNIT_NAME>\impex\src.
The existence of whitestore-democontent.zip in import source directory is the key prerequisite for the next step, the installation.
Installation
The preparation process depicted and explained above is key for the actual installation process that this chapter is about. As the actual trigger for the preparation process is the creation of a new unit, the installation has to be performed later on. After the organization manager created a new sales channel this message:
is displayed. That is a hint to remind the person that white label store content must still be installed as the newly created sales channel will not contain any data. The installation process would take to long to be started along with unit creation (connection time out).
Another possible way to be reminded of the missing installation is when entering the Design View of the newly created business unit. A page containing this
message can appear in such a case. Giving the back office user the chance to decide between two options.
The option Prepare Application Content starts the white label store installation.
The option Start from scratch allows to build up the contents of the storefront from scratch.
Option Prepare Application Content is only available if a whitestore content archive has been found and the user has necessary access privileges.
Option Start from scratch is only available if the user has necessary access privileges.
The actual installation is done by leveraging the standard import process. For a successful installation it just needs to have the content archive prepared and in place. It is assumed that this is to be found in the impex source directory of the newly created business unit. The archive's name must be whitestore-democontent.zip.
Unit name replacement
One word has to be mentioned about the necessity to replace all unit names contained in the content archive. As white label store content is just a standard import archive it contains unit name references per import entity. These references are not working for every single unit name possible to be created. A unit name usually consists of different object ID values (organization, channel etc.) concatenated together. Therefore, some import filter is used to translate the original unit name (contained in the applied white store content archive) into whatever target unit name.
| Original unit name | target unit name (example) | Unit type |
|---|---|---|
| Organization-Channel | Foo-Bar | channel |
| Organization-Channel-Application | For-Bar-B2C | application |
The target unit name in the example above is put together out of the organization named Foo, out of the channel named Bar and the application named B2C. Unit name replacement for the different unit types can only work mutual exclusive. Meaning, a white store content archive for a channel should not contain references to organization-channel-application and vice versa.
This technical requirement applies only if Customization & Production is an option (see prerequisite rule 2below).
Customization & Production
Prerequisites
A few rules have to be obeyed when creating new or customize existing white label store content.
Rule 1
As white label store content is intended for newly created units the objects referred by such content must not be unit dependent. Exeptions are only intra unit references to be contained by all white label store content.
Explanation:
Suppose you have a component that refers to some catalog category. If that component would be part of white label store content, the import is likely to fail on resolving that category reference for some new created channel or application. The same applies to images, products, anything that is not covered by white label store content (as defined above). Therefore such references must be avoided.
Rule 2
Channel white label store content can only be used to prepare channels and not applications. The same applies vice versa: Application white label store content can only be used to prepare applications and not channels.
Explanation:
That is because of the mechanism that translates the fixed domain name of the input source into the target domain name.
Rule 3
Any conditions that lead to refactoring a given content model element (e.g., renaming some pagelet definition) must be planned and also executed for the white label store content. Otherwise, a unit may contain instances refering to the old named content model element.
Production
As said above, it is possible to install white label store content that deviates from Intershop's standard demo scenario PrimeTech. It just has to obey the prerequisites from the section above and has to be locatable by the preparation process. A small guideline is as follows:
- Create a new unit in which production takes place.
- Import or create content from scratch.
- Verify that prerequisite rules from above hold true for the imported or created content.
- Repeat 2 and 3 until complete.
- ZIP export all content contained in the production unit.
- Download and unzip the archive to a place where it can be shared with others.
This guideline shall only convey what steps are necessary to build a new white label store archive. It cannot provide a detailed list of tasks as everything depends on how content objects are introduced (2) to the production unit. It also depends on what is contained in the content (e.g., image, category and product references). Step 4 applies until the white label store is complete. What this means has to be determined individually.
The last step depends on how objects of the shared files system ( $IS_SHARE\sites ) are distributed in some organization. Important to know is that the preparation processmust be able to locate it by applying the described mechanisms. That means, the properties file whitestorecontent.properties residing in sld_ch_consumer_plugin/release/config has to be modified. If this is not possible, the file can be copied and modified to a custom cartridge that is loaded after sld_ch_consumer_plugin.