Concept - Storefront Preview IS7 (valid to 7.4 CI)

1 Preview Configuration Framework

This chapter describes how to use the Storefront Preview Configuration Framework to set up an individual storefront preview. The Storefront Preview Configuration Framework can set up an individual preview with specific preview functions for each application type (see Application Framework ).

1.1 Preview Configuration Attributes

Preview Configuration Attributes play a double role in the Storefront Preview Configuration Framework. The first role relates to the configuration process. A Preview Configuration Model is set up using the component framework. A Preview Configuration Model consists of several Preview Configuration Attributes. In apps.components this Preview Configuration Model is wired to the application.

DIA PreviewConfigurationModel UML

You can choose from two different Model implementations: MapBasedPreviewConfigurationModel and ListBasedPreviewConfigurationModel. One is a list-based implementation, the other one is map-based (default - shown below). A list-based implementation pertains the order in which Preview Configuration Attributes are wired, but its runtime performance is proportional to the amount of attributes it contains. The (hash) map-based implementation performs better but does not pertain the order of wiring.

...
<instance name="intershop.B2CWebShop.PreviewConfigurationModel" with="PreviewConfigurationModel">
        <fulfill requirement="configurationAttributeFactory">
             <instance with="PreviewDateFactory" />
             <instance with="PreviewLocaleFactory" />
             <instance with="PreviewCurrencyFactory" />
             <instance with="PreviewPromotionFactory" />
             <instance with="PreviewUserGroupFactory" />
			 <instance with="PreviewCampaignFactory" />
             <instance with="PreviewABTestGroupFactory" />
             <instance with="PreviewTargetUrlFactory" />
             <instance with="PreviewApplicationFactory" />
        </fulfill>
        <fulfill requirement="configurationAttributeFactory" with="CatalogCategoryOnlineIgnoredAttributeFactory" />
        <fulfill requirement="configurationAttributeFactory" with="ProductOnlineIgnoredAttributeFactory" />
        <fulfill requirement="configurationAttributeFactory" with="ProductAvailabilityIgnoredAttributeFactory" />
    </instance>
...
    <instance name="intershop.enfinity.B2CWebShop" with="ApplicationType">
...
        <fulfill requirement="namedObject">
         <instance with="NamedObject">
             <fulfill requirement="name" value="PreviewConfigurationModel" />
             <fulfill requirement="object" with="intershop.B2CWebShop.PreviewConfigurationModel" />
         </instance>
        </fulfill>
...
    </instance>

For each specific PreviewConfigurationAttribute, the PreviewConfigurationModel needs the corresponding factory. These factories create the PreviewConfigurationAttribute instances.

The second role relates to the preview process. An instance of the PreviewContextBO class is created based on the Preview Configuration Model of the previewed application. Each Preview Configuration Attribute of a PreviewContextBO instance holds specific information (e.g values) the back office user has given to control a certain storefront preview.

DIA PreviewContextBORepository UML

Several specific Preview Configuration Attributes are available. The following table describes the properties which all Preview Configuration Attributes have in common.

Property

Type

Description

ID

String

Each Preview Configuration Attribute has a unique identifier which is used for access.

selected

Boolean

An attribute is selected if it contains at least one selected value. The returned value is calculated based on (user or default) selected values.

enabled

Boolean

An attribute is enabled if it is allowed to contain values or if it is not in conflict with any other selected value of depending attribute instances.
This value is also calculated based on the selection state of other depending attribute instances.

singleValued

Boolean

An attribute is single-valued if it is only allowed to contain one or zero selected values during its lifetime.

visible

Boolean

Defines whether the attribute is visible in the back office preview panel.

group

String

The (display) group of this attribute. The group is set by the factory that creates this attribute.

Each PreviewConfigurationAttribute<T> holds a collection of instances of PreviewConfigurationAttributeValue. Every instance represents a selectable value for the preview configuration process (=Design View). All PreviewConfigurationAttribute<T> implementations delivered in this release have their own inner class factory implementations to create new instances of themselves. Instances of PreviewConfigurationAttributeValue hold a semantic giving value object of any given class (T).

Example:

The PreviewDateAttribute implements PreviewConfigurationAttribute<Date> and holds a single instance of PreviewConfigurationAttributeValue. The class of this value instance is PreviewDateAttributeValue. PreviewDateAttributeValue holds an instance of the class Date as semantic giving value.
In contrast to PreviewDateAttribute, PreviewLocaleAttribute holds several instances of PreviewLocaleAttributeValue. Each instance of PreviewLocaleAttributeValue holds a value object of class LocaleInformation which stands for an available LocaleInformation object the user may choose from. One PreviewLocaleAttributeValue holds the default locale which is always (without user interaction) the selected value for preview.

The following picture gives an overview:

Preview Configuration Attribute

The following table lists all Preview Configuration Attributes available in this release:

ID

Class

Factory Implementation

Value Object Type

Description

Visible

Single-valued

Enabled

Default Values

Pipeline Dictionary Keys (mandatory|optional)

PreviewDate

PreviewDateAttribute in bc_preview

PreviewDateFactory in implementations.component
of bc_preview

Date

The Date being used for storefront rendering.
If no date value is selected, the current server time is used for preview.

true

true

true

Its instantiation time

none

PreviewLocale

PreviewLocaleAttribute in bc_preview

PreviewLocaleFactory in implementations.component
of bc_preview

LocaleInformation

The LocaleInformation being used for storefront rendering.
Set of possible values is equal to the set of supported system languages.

true

true

true

The target application default locale or the systems lead locale.

TargetApplication(m)

PreviewCurrency

PreviewCurrencyAttribute in bc_preview

PreviewCurrencyFactory in implementations.component
of bc_preview

Currency

The Currency being used for storefront rendering.
Set of possible values is equal to the set of supported active currencies (for a given domain).
Possibly a permission is necessary when changing a value.

true

true

true

The target applications default currency or the systems lead currency.

TargetApplication(m)

PreviewTargetURL

PreviewTargetUrlAttribute in bc_preview

PreviewTargetUrlFactory in implementations.component
of bc_preview

String

Conceptually, the back office item to be previewed must be used to create an application-specific URL using the call interface (described later). The implemented attribute is the place where this URL is expected to be stored.

false

true

true

none

none

PreviewApplication

PreviewApplicationAttribute in bc_preview

PreviewApplicationFactory in implementations.component
of bc_preview

Application

We need this attribute to allow switching between all available applications within the given channel. The target URL of the preview panel must use the URL identifier of the selected application.

true

true

true

The preferred preview application that has been selected in the user profile for the given channel, or the default application of the channel.

RepositoryDomain (m)
RepositoryId (m) CurrentUser (m)

PreviewUserGroups

PreviewUserGroupAttribute in bc_marketing

PreviewUserGroupFactory in preview-implementations.component
of bc_marketing

UserGroup

The Collection<UserGroup> that is used for the current storefront user.
Set of possible values is equal to the set of consumer groups created in the given channel (Taken from PreviewConfigurationAttributeContext).
Depends on Promotion, ABTest and Campaign attribute values.

true

false

true

none

CurrentChannel (m)

PreviewDisplayDevice

PreviewDisplayDeviceAttribute in bc_preview

PreviewDisplayDeviceFactory in implementations.component
of bc_preview

DisplayDevice

To select a frame size in which the previewed application will be displayed, making it possible to display a storefront on limited screen size.

true

true

true

The browser calculated frame size.

RepositoryDomain(m)
RepositoryId (m) 
CurrentUser (m)

PreviewPromotions

PreviewPromotionAttribute in bc_marketing

PreviewPromotionFactory in preview-implementations.component
of bc_marketing

Promotion

The Collection<Promotion> that will be applied upon storefront preview.
Currently it can only contain one item (the previewed promotion). The set of possible values will be empty.

false

true

true

none

none

PreviewCampaigns

PreviewCampaignAttribute in bc_marketing

PreviewCampaignFactory in preview-implementations.component
of bc_marketing

Campaign

The Collection<Campaign> that will be applied upon storefront preview.
Currently it can only contain one item (the previewed campaign). The set of possible values will be empty.

false

true

true

none

none

PreviewABTestGroups

PreviewABTestGroupAttribute in bc_marketing

PreviewABTestGroupFactory in preview-implementations.component
of bc_marketing

ABTestGroup

The Collection<ABTestGroup> being used for storefront rendering.
Currently it can only contain one item (the previewed ABTest group).
The set of possible values will be empty.

false

true

true

none

none

CatalogCategoryOnlineIgnoredAttribute

PreviewBooleanAttribute in bc_preview

PreviewBooleanFactory in instances.component
of bc_mvc

Boolean

Tells the Application that evaluates this setting whether a catalog category that is not online should be rendered or not.

true

true

true

true

none

ProductOnlineIgnoredAttribute

PreviewBooleanAttribute in bc_preview

PreviewBooleanFactory in instances.component
of bc_mvc

Boolean

Tells the application that evaluates this setting whether a product that is not online should be rendered or not.

true

true

true

true

none

ProductAvailabilityIgnoredAttribute

PreviewBooleanAttribute in bc_preview

PreviewBooleanFactory in instances.component
of bc_mvc

Boolean

Tells the application that evaluates this setting whether a product that is not available should be available for checkout or not. 
It will not be visible in preview configuration panel.

false

true

true

false

none

ProductInventoryIgnoredAttribute

PreviewBooleanAttribute in bc_preview

PreviewBooleanFactory in instances.component
of bc_mvc

Boolean

Tells the application that evaluates this setting whether a product for which a configured inventory service has delivered a result should be available for checkout or not.

true

true

true

true

none

1.1.1 Preview Configuration Attribute Context

Some of the above-listed Preview Configuration Attributes receive further information from variables found in the pipeline dictionary (Pipeline Dictionary Keys). For instance, in order to determine all consumer groups of a given channel, a PreviewUserGroups attribute needs to know the channel for which attribute values should be returned. The purpose of PreviewConfigurationAttributeContext is to allow remapping values from the pipeline dictionary to the internal API PD keys (shown above). A Preview Configuration Attribute can declare depending keys using the PreviewConfigurationAttributeContextKey annotation. During the creation of PreviewConfigurationAttributeContext (via pipelet) a lookup will be executed for value existence of all mandatory PD keys of preview configuration attributes contained in the given model. If any value of a mandatory PD key is missing, a pipelet execution exception is thrown. There is no general way to provide these values except the caller of the pipelet has to make sure that all mandatory values of the site's preview configuration model are available.

The PreviewConfigurationAttributeContext default implementation can be replaced by your own custom implementation. A factory instance can simply be "wired" using the IS7 componentization framework. The create pipelet is looking for a named instance to create new PreviewConfigurationAttributeContext objects. bc_preview registers the default implementation in its component files.

1.1.2 Preview Configuration Attribute Set

The ID value to access the different Preview Configuration Attribute (PCA) objects (e.g. PreviewDateAttribute) has to be maintained by a Java enum type. All PCAs defined in cartridge bc_preview are aggregated in such an enum named PreviewConfigurationAttributeSet. Each cartridge which defines new Preview Configuration Attributes should follow this example. All pipelets (described below) that work with a particular PCA can use this enum mechanism to identify an object. Your own attribute set enum has to implement PreviewConfigurationAttributeID and it can automatically be used in all PCA pipelets. To be precise, besides providing the enum class you also have to specify the enum value as a string (e.g. "PreviewDate").

1.2 Available Pipelets

The following three tables list all pipelets of bc_preview available in this release:

1.2.1 Pipelets for Management of the Preview Configuration Attribute Context

Pipelet Name

Description

Configuration

In Properties
(mandatory|optional)

Out Properties

Has Error Connector

CreatePreviewConfigurationAttributeContext

Creates a PreviewConfigurationAttributeContext object for the given configuration model. All mandatory PD keys of all preview configuration attributes contained in the model must lead to a value. The value is determined by a fallback:

  1. ConfigurationAttributeMap is searched
  2. The pipeline dictionary is searched
  3. A PipeletExecutionException is issued telling which values of which configuration attribute are missing.

none

ConfigurationAttributeMap:Map (opt.) PreviewConfigurationModel:PreviewConfigurationModel (mand.)

PreviewConfigurationAttributeContext:PreviewConfigurationAttributeContext

no

1.2.2 Pipelets for the Management of the Preview Configuration Attributes

Pipelet Name

Description

Configuration

In Properties
(mandatory|optional)

Out Properties

Has Error Connector

GetPreviewConfigurationAttribute

Returns a PreviewConfigurationAttribute from a PreviewContextBO. The PreviewConfigurationAttribute is selected either by the given PreviewConfigurationAttributeID or by the attribute set enum (described above) in combination with an enum value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)

PreviewConfigurationAttribute:PreviewConfigurationAttribute

no

GetPreviewConfigurationAttributeID

Returns a PreviewConfigurationAttributeID value from a given (PreviewConfiguration)AttributeSet in combination with an AttributeSetValue (which is the enum value)

AttributeSet:Class AttributeSetValue:String

none

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID

no

DeselectPreviewConfigurationAttribute

Deselects all selected values of a PreviewConfigurationAttribute from a PreviewContextBO. The PreviewConfigurationAttribute is selected either by the given PreviewConfigurationAttributeID or by the attribute set enum (described above) in combination with an enum value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)

none

no

ResetPreviewConfigurationAttribute

Resets a PreviewConfigurationAttribute from a PreviewContextBO to its default values, which means all existing attribute values will be removed and default values will be calculated again. The PreviewConfigurationAttribute is selected either by the given PreviewConfigurationAttributeID or by the attribute set enum (described above) in combination with an enum value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)

none

no

SetSelectedPreviewConfigurationAttributeValue

Sets one attribute value of a PreviewConfigurationAttribute to selected:=true. The attribute value is identified using the given value object. The PreviewConfigurationAttribute is selected either by the given PreviewConfigurationAttributeID or by the attribute set enum (described above) in combination with an enum value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)
ValueObject:Object (mand.)

none

no

SetSelectedPreviewConfigurationAttributeValues

Sets several attribute values of a PreviewConfigurationAttribute to selected:=true. The attribute values are identified using a collection of value objects. The PreviewConfigurationAttribute is selected either by the given PreviewConfigurationAttributeID or by the attribute set enum (described above) in combination with an enum value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)
ValueObjects:Collection (mand.)

none

no

GetSelectedPreviewConfigurationAttributeValueObjects

Get all selected (attribute) values of a preview configuration attribute in the context of the given PreviewContextBO. The selected values are returned as their semantic giving value.

AttributeSet:Class AttributeSetValue:String

PreviewConfigurationAttributeID:PreviewConfigurationAttributeID (opt.) PreviewContextBO:PreviewContextBO (mand.)

ValueObjects:Collection (opt.)

no

1.2.3 Pipelets for the Management of the Preview Context

Pipelet Name

Description

Configuration

In Properties
(mandatory|optional)

Out Properties

Has Error Connector

CreatePreviewContext

Creates a new PreviewContextBO under the given ID and based on the given PreviewConfigurationModel. An optional PreviewConfigurationAttributeContext allows you to supply all contained PCA objects with their dependent objects

none

ID:String (mand.)
PreviewConfigurationAttributeContext:PreviewConfigurationAttributeContext (opt.) PreviewConfigurationModel:PreviewConfigurationModel (mand.)

PreviewContextBO:PreviewContextBO

no

GetPreviewContextByID

Returns the found PreviewContextBO identified by the ID value. If no PreviewContextBO under the given ID has been found, the error node is used.

ID:String

ID:String (opt.)

PreviewContextBO:PreviewContextBO

yes

RemovePreviewContext

Removes the given PreviewContextBO.

none

PreviewContextBO:PreviewContextBO (mand.)

none

no

CreateFullSitePreviewContextBO

From a given PreviewContextBO it creates a new PreviewContextBO instance for a full site. If the given PreviewContextBO is not capable of generating a full site preview, the error exit is used. A PreviewContextBORepository to create a full site preview context has to be provided by the caller.

none

PreviewContextBO:PreviewContextBO (mand.)
FullSitePreviewContextBORepository:PreviewContextBORepository (mand.)

FullSitePreviewContextBO:PreviewContextBO

yes

CopyIntersectValues

This pipelet copies attribute settings from one PreviewContextBO to another PreviewContextBO. Values must be part of attributes that are elements of the intersection set of corresponding PreviewConfigurationModel objects.

none

PreviewContextBOSource:PreviewContextBO (mand.)
PreviewContextBODestination:PreviewContextBO (mand.) in/out

none

no

2 Preview Webform Usage

As each PreviewContext can consist of various PreviewConfigurationAttributes, there has to be a way to dynamically access them and display them in a preview panel like this:

This concept describes how this can be done.

2.1 Glossary

PCA

PreviewConfigurationAttribute - refers to the interface com.intershop.component.preview.capi.configuration.PreviewConfigurationAttribute

PCAV

PreviewConfigurationAttributeValue - refers to the interface com.intershop.component.preview.capi.configuration.PreviewConfigurationAttributeValue

PrevCon

PreviewContextBO - refers to the interface com.intershop.component.preview.capi.context.PreviewContextBO

2.2 A Schematic Overview

The following picture outlines the schematic overview:

SchematicOverview

The picture shows the tactic while getting all PCA from a given PrevCon. With getPreviewConfigurationAttributes() a list of all available PCA is fetched. For any of these PCA a webform file must exist which is looked up. If one is found, the com.intershop.beehive.emf.webform.FormParameterDefinition in this file is used to create a new com.intershop.beehive.core.capi.webform.FormParameter which afterwards is put into a newly created com.intershop.beehive.core.capi.webform.Form.

Inside ISML a loop over the form members is performed and an ISML snippet for any contained FormParameter will be looked up. If again one is found, the FormParameter will be rendered with this particular ISML snippet (using a <isinclude> call).

So we can make sure that we have a dynamic way of showing the different PCA and to display them in the proper HTML style (like text inputs, select boxes, radio buttons, ...).

The identifier for all the different parts (webform file, ISML snippet) is always the (unique) ID of the PCA.

2.3 The Webform Definition

The name of the webform file has to be the ID of the PCA. According to the webform "convention", the name of the FormDefinition has to be the same as the file name, so this also has to be the ID of the PCA. We do create one webform file for each PCA, so in every webform file only one FormParameterDefintion should be present - which will represent the PCA.

You can use existing and self-written form validators, both will be supported by the webform framework.

A FormParameter can have an object assigned, which represents the value of the FormParameter. Using the CreateConfigurationPanelWebform piplet, this object will always be the PCA behind the parameter type (i.e. FormParameterDefintion). This fact is important as some information cannot be provided in the FormParameter but is important for displaying the PCA in the preview panel (like visible, enabled, ...).

Note that if you want to update a preview webform with values from a submitted HTML form, you need to perform two steps (following the general webform pattern): 1) create a webform and 2) update the webform. For these purposes a pipeline was created, using a number of pipelets (see below).

2.4 Implementation Details

2.4.1 Class: PreviewFormParameter

An enhancement of the FormParameter class has been created, which is specialized to use a PCA as its value object. The class inherits any functionality that the FormParameter provides but in addition it ensures that the value object is of type PCA. The class is com.intershop.sellside.preview.capi.webform.PreviewFormParameter.

However, this implementation is added via the CreateConfigurationPanelWebform to the resulting webform and acts like any other FormParameter. So no problem occurs when using it within other forms.

2.4.2 Validators

To validate the values for a PreviewFormParameter that are sent within the request, a number of new validators were created. These validators were enhanced to contain a PrevCon and will be used for validating the request values. Therefore, an interface was created: com.intershop.sellside.preview.capi.webform.PreviewValidator.

The validators are:

  • Preview-BooleanValidator: ensures that a PCA is selected using a boolean value
  • Preview-MultiSelectionValidator: ensures that a PCA is updated with a collection of values that is part of the PCA's value domain
  • Preview-SingleSelectionValidator: ensures that a PCA is only updated with one value that is also part of the PCA's value domain
  • Preview-TargetUrlValidator: sets the current storefront URL as new selected value of PCA - PreviewTargetURL
  • Preview-DateValidator: syntactically checks and sets a date value if 'fixed' has been selected, removes selected value (if any) in other cases. Since 7.3, it will also check if the date is in the past in case the domain preference DisablePreviewForPastDates is enabled.
  • Preview-JustSynchronize: just changes the selected state of all contained PCAV objects according to the webform; this means there is no validation whatsoever.

These validators were defined in the sld_preview/staticfiles/webforms/previewpanel/Preview.webform file, so that they can easily be attached to any form definition.

2.4.3 Pipelets

2.4.3.1 CreateConfigurationPanelWebform

This pipelet uses a given PrevCon and builds up a Form which can be used to display on an HTML page (using ISML code). The pipelet loops over all given PCA and tries to find corresponding FormDefinitions with proper FormParameterDefinitions (see above). The pipelet uses the PreviewFormParameter class to add to the form, so that it is ensured that the value object is the PCA.

2.4.3.2 ValidateConfigurationPanelWebform

This pipelet acts like the existing core pipelet ValidateForm but a PrevCon is added to the validation. The reason for this is that some PCA need the context as their value source for the context validation.

Since 7.3, an additional parameter ValidatorContextParams of type Map<String,String> has been added which adds additional configuration parameters as key-value-pairs to the ValidatorContext. This allows to e.g. provide the preview validators with additional necessary dynamic info for validation.

Note: The pipelet not only validates, it also updates the value of the created form (by using CreateConfigurationPanelWebform) with all values given within the current request. This means you need to use this pipelet also to get the values from the request into your webform. The pipelet performs two steps: 1) update the webform and 2) validate the values of the webform parameters with the attached value objects (which are PCA).

2.4.4 Pipelines

One process pipeline with two start nodes was created to handle webform creation and webform validation. The pipeline is called ProcessConfigurationPanelWebform, and the start nodes are Create for creating a new webform and Update for updating a webform and validating it.

2.4.5 ISML Snippets

2.4.5.1 Module: PreviewFormParameter.isml

This ISML snippet defines an ISModule that is used to determine the proper ISML snippet for a specific PreviewFormParameter. The module is defined in preview/Modules and uses the formParameter, the previewContext and the CurrentRequest as attributes. The form parameter and context are mandatory. If they are not set, the module will not proceed.

Based upon the ID of the formParameter (formParameter.getID()) the module tries to determine an ISML code snippet with "preview/" + ID + ".isml". This snippet will be loaded, and the form parameter and context will be passed through.

2.4.5.2 Form Parameter ISML Snippets

The form parameter ISML snippets are used to display the PCA in their proper presentation in an HTML page. The snippets should only contain HTML form elements (like radio buttons, selects and so on) but not a new form declaration itself.

There is a major aspect of these snippets: if the given form parameter is invalid (formParameter:Invalid EQ 'true'), the values that should be shown shall be taken from the form parameter or from the form parameter's fields - not from the attached value object. The reason for that is that, if you submit a form, the ValidateConfigurationPanelWebform first validates the submitted string values, and if they are valid, it updates the corresponding PCA. If they are not valid, they will be set at the form parameter (to show the user the wrong values) but not set at the PCA. This behavior also means that if the form parameter is valid (NOT formParameter:Invalid EQ 'true'), you should get the values to display from that attached PCA as if they represent the current state.

The form parameter ISML snippets should also take care about the PCA's visibility attributes. If visible or enabled are set to false, the webform elements should not be shown. They should either be hidden or not added to the HTML at all.

2.4.5.3 Module: PreviewPanelError.isml

The module isPreviewPanelError is created to dynamically display error messages based upon the form parameters that failed in the validation process. The module takes an attribute called previewFormParameter and either shows an error message if an error was defined within that module or tries to load another ISML snippet from the following source: "preview/error/" + previewFormParameter:ID.

With this module you will be able to create independent ISML snippets to display error messages for failed form parameter validation.

3 Transfer of Preview Context

The preview configuration webform displayed in the preview settings panel (Design View) runs within the back office session. On the contrary, the previewed application must run within its own HTTP session including possible URL manipulation. However, preview settings must be accessible from the previewed application, otherwise none of the shown pages would be meaningful.

3.1 Implementation

3.1.1 Transferable Extension

The whole transfer mechanism is based on the possibility to render the contents of a preview context as transferable pieces of data. This is happening all the time the context is updated by the user when clicking the 'OK' button (plus webform validation was successful). Transferable pieces are stored as hidden form values and will be transmitted to the target site via an AJAX call from JavaScript (designer.js). The pipeline that is called and that is supposed to be available is ViewPreviewConfiguration-UpdateSession. The cartridge sld_preview contains such a pipeline. Its only task is to create a new preview context for the receiving storefront application and reload its content with the transferable pieces part of the current request.

3.1.2 Security

If you feel that this solution is a potential risk for your system (live or edit stage), be aware that technically you can switch off the whole preview feature. With a purpose there is no code dependency between an application cartridge and sld_preview.

In addition, the transferable pieces of data are encrypted before transmission.

3.1.3 Necessary Customization

As described in the present concept document, to create a preview context one necessary step is to provide a none-empty Preview Configuration Attribute Context. ViewPreviewConfiguration-UpdateSession is executing a call to ProcessPreviewAttributeContext-CreateConfigurationAttributesMap in order to do that.

4 Full Site Preview

With the full site preview function you can open a complete separate browser window and view the storefront with the preview settings given in "Design View".

4.1 Create Full Site Preview Context

The values stored in the "Design View" preview context are made persistent using a PreviewContextPO instance. In preparation of the full site preview the system performs the following steps:

  1. Create a new and empty PreviewContextPO object by using PreviewContextMgr
  2. Copy "Design View" configuration panel settings into new PreviewContextPO
  3. Return created persistent object as a subtype of PreviewContextBO

All of the above-listed processes are incorporated in a pipelet CreateFullSitePreviewContextBO. The caller of this pipelet must provide a PreviewContextBORepository value so that the first step is actually hidden behind the create-method of the given value. Now, the PreviewContextBORepository implementation that actually delivers the creation of a PreviewContextPO can be accessed via this object path: ApplicationBO:Repository("PreviewContextBORepository").

The created PreviewContextBO carries a unique ID (per domain) which is used to identify the created full site preview context. Its value is encrypted and is part of the full site preview URL. The domain name of the source application and their URL identifier, which will be used to identify the source application, are also part of this URL. The preview URL can also be sent via mail or IM.

4.2 Get Full Site Preview Context

The goal of full site preview is to create a distraction-free preview of the storefront with a URL that can be shared with others. As explained above, the persistent preview context is identified by a unique ID. This ID value is encrypted for security reasons and must be decrypted prior to the lookup of the object identified.

Getting the full site preview context involves the retrieval of a PreviewContextBORepository value. This is done using the same object path when creating the full site preview context (chapter above). Obviously finding the correct ApplicationBO is a prerequisite of full site preview context lookup. This is done via domain name and URL identifier of the source application. Both values are also a part of the Full Site Preview Link.

If the preview for past dates is disabled then the PreviewContextBORepository uses a PreviewConfigurationAttributeMapper for the preview date attribute. This mapper does not return the persistently stored preview date if this date refers to the past. Instead, it behaves like an unselected preview date attribute (which means use current time). If the stored preview date refers to the future, it is safe for the mapper to behave like a selected preview date attribute (which means use the fixed time). All that is to guarantee that the preview date is not in the past if the preview for past dates is disabled.

A URL of a created full site preview context can be shared with others. Such URLs just have a certain life time ( 180 days by default) that can be configured via the Preview purge job's attribute set. Log on to the SMC in order to manage the life time of preview links.

5 Preview Purge Job

This section describes the purpose and use of this job. The storefront preview is shown in the context of the Design View, i.e., the previewed storefront is shown in a separate window based on the configuration panel settings of the design view. The settings are treated independently from the settings of the Design View, i.e., even though they are initially the same, the changes applied in the design view do not affect the settings used in the separate preview window (so it is a deep copy of the settings).

These settings are made persistent for each preview and stored as a PreviewContext object in a database. These objects are never updated; instead, a new link implies a new PreviewContext  object. As for each preview a new object is created, the related database table might grow very big. This is why a regular cleanup has to be performed. Any obsolete PreviewContext is deleted via a Job Preview Context Cleanup.

5.1 Job Descriptor

The preview purge job is created during dbinit/dbmigrate of cartridge bc_preview_orm. For the parameters configured during creation the job is executed after a definite time interval. A job with the name "Preview Context Cleanup" is introduced that performs a cleanup. The job details are as follows:

Job Attributes:

  • Name: Preview Context Cleanup
  • Pipeline: ProcessPreviewContextCleanup-Start
  • Description: Removes outdated fullsite preview links.
  • Interval: 1,440 (mins)
  • AttributeName1: LifeTime
  • AttributeType1: Integer
  • AttributeValue1: 180

The attribute LifeTime is n number of days, any PreviewContext  that is n days older than the current date is considered as obsolete by this job.

5.2 Implementation Details

All job-related artifacts are in cartridge bc_preview_orm. The job pipeline start node ProcessPreviewContextCleanup-Start is a strict node with LifeTime as one of the mandatory parameters. The algorithm of the job is as follows:

  1. The job pipeline first computes the date which needs to be used when retrieving the obsolete PreviewContext objects. The calculation logic is:

    ComputedDate = CurrentDate - LifeTime(no of days)
  2. Execute the objects query to retrieve the object from table PREVIEWCONTEXT with lastmodified < ComputedDate.
  3. The pipelet PurgePersistentPreviewContexts is responsible for deleting the above objects from the database using the orm method.

6 Application Switch and Page Fallback

In principle, a preview user can switch between different applications using the design view settings panel. However, some problems arise when pipelines differ from application to application. A general error or a 404 error page might occur because the pipeline is missing.

To help users out of this misery, an application page fallback has been requested. The concept behind the implementation of this request will be described in this document.

DIA Application CallInterface UML Object

6.1 Application Switch

An application switch means that preview settings are always stored per "storefront" application inside a PreviewContextBO object. As described in other concept papers of storefront preview the configuration model itself is configured at the application type level, leaving the configuration model also application- or application type-specific - e.g., a mobile application might have other display size values than a full-blown storefront. In reaction to this the settings panel has to show only the attributes and values that are valid with regard to a newly selected application -> application switch.

A pipeline call is executed from JavaScript every time the preview configuration attribute named PreviewApplication changes its value. The pipeline that is executed is called EditView-ChangeApplication. The preview context that is currently "active" (the one where attributes and attribute values are shown in the settings panel) will not be updated by this switch. It just determines the ID of the new application value, semantically speaking that is the Url-Identifier value. With that value the Application and the ApplicationBO can be retrieved. A new PreviewContextBO based on the ApplicationBO is created and values of common preview attributes are copied from the "active" context (if attribute has been changed by user). Based on the newly created and synchronized context a webform is created and shown in the settings panel dialog.

6.2 Application Call Interface

For direct item preview we already introduced a call interface that takes the user from any (supported) back office item list or detail page to the position in the storefront where this item is shown. Documentation about this is necessary as this mechanism is only successful if the application developer tells the preview framework where to go. The cookbook explains the required implementation steps in more detail.

The existing interface will contain a new method public String resolve(String urlString) to resolve a string-based URL and return a new URL capable of executing a storefront call in a new application context.

6.3 B2C Application Call Interface

This class is the reference implementation of an application call interface. Let us concentrate on the resolve method as this document only explains the concept behind the page fallback.

The internal implementation delegates to a set of configured (i.e., /sld_ch_b2c_app/staticfiles/cartridge/config/applicationcallinterface.properties) classes. Each class is responsible for handling specific "view pipeline" URLs for their associated type. E.g., class B2CApplicationCallInterfaceProduct tries to resolve URLs that show a product, class B2CApplicationCallInterfaceCatalogCategory tries to resolve URLs that show a catalog category and so on. It is the responsibility of the application to deliver the logic necessary for such URL conversions.

If the above resolving fails to return a none null value, it asks the new application context whether or not the pipeline (taken from the method parameter urlString) exists. An existing pipeline means that the given URL can just be returned. A none-existing pipeline means that a call to the given URL is likely to fail.

At this point only Default-Start can be resolved as the pipeline that receives the URL call.

7 References

Overview - Webforms,
Overview - Component Framework

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