This section 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).
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.
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="PreviewCustomerSegmentBOFactory" /> <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.
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. |
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:
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 |
|
|
| The Date being used for storefront rendering. | true | true | true | Its instantiation time | none |
PreviewLocale |
|
|
| The LocaleInformation being used for storefront rendering. | true | true | true | The target application default locale or the systems lead locale. | TargetApplication(m) |
PreviewCurrency |
|
|
| The Currency being used for storefront rendering. | true | true | true | The target applications default currency or the systems lead currency. | TargetApplication(m) |
PreviewTargetURL |
|
|
| 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 |
|
|
| 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) |
PreviewUserGroups |
|
|
| The Currently in preview context UserGroup assignments are used for: content components, shipping rules and payment methods. | true | false | true | none | CurrentChannel (m) |
PreviewCustomerSegmentBOs |
|
|
| The | true | false | true | none | none |
PreviewDisplayDevice |
|
|
| 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) |
PreviewPromotions |
|
|
| The | false | true | true | none | none |
PreviewCampaigns |
|
|
| The | false | true | true | none | none |
PreviewABTestGroups |
|
|
| The | false | true | true | none | none |
CatalogCategoryOnlineIgnoredAttribute |
|
|
| 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 |
|
|
| 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 |
|
|
| Tells the application that evaluates this setting whether a product that is not available should be available for checkout or not. | false | true | true | false | none |
ProductInventoryIgnoredAttribute |
|
|
| 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 |
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.
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"
).
The following three tables list all pipelets of bc_preview available in this release:
Pipelet Name | Description | Configuration | In Properties | Out Properties | Has Error Connector |
---|---|---|---|---|---|
CreatePreviewConfigurationAttributeContext | Creates a
| none | ConfigurationAttributeMap: | PreviewConfigurationAttributeContext: | no |
Pipelet Name | Description | Configuration | In Properties | 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: | PreviewConfigurationAttributeID: | PreviewConfigurationAttribute: | no |
GetPreviewConfigurationAttributeID | Returns a PreviewConfigurationAttributeID value from a given (PreviewConfiguration)AttributeSet in combination with an AttributeSetValue (which is the enum value) | AttributeSet: | none | PreviewConfigurationAttributeID: | no |
DeselectPreviewConfigurationAttribute | Deselects all selected values of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
ResetPreviewConfigurationAttribute | Resets a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
SetSelectedPreviewConfigurationAttributeValue | Sets one attribute value of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
SetSelectedPreviewConfigurationAttributeValues | Sets several attribute values of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
GetSelectedPreviewConfigurationAttributeValueObjects | Get all selected (attribute) values of a preview configuration attribute in the context of the given | AttributeSet: | PreviewConfigurationAttributeID: | ValueObjects: | no |
Pipelet Name | Description | Configuration | In Properties | Out Properties | Has Error Connector |
---|---|---|---|---|---|
CreatePreviewContext | Creates a new | none | ID: | PreviewContextBO: | no |
GetPreviewContextByID | Returns the found | ID: | ID: | PreviewContextBO: | yes |
RemovePreviewContext | Removes the given | none | PreviewContextBO: | none | no |
CreateFullSitePreviewContextBO | From a given | none | PreviewContextBO: | FullSitePreviewContextBO: | yes |
CopyIntersectValues | This pipelet copies attribute settings from one | none | PreviewContextBOSource: | none | no |
This section 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).
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.
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="PreviewCustomerSegmentBOFactory" /> <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.
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. |
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:
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 |
|
|
| The Date being used for storefront rendering. | true | true | true | Its instantiation time | none |
PreviewLocale |
|
|
| The LocaleInformation being used for storefront rendering. | true | true | true | The target application default locale or the systems lead locale. | TargetApplication(m) |
PreviewCurrency |
|
|
| The Currency being used for storefront rendering. | true | true | true | The target applications default currency or the systems lead currency. | TargetApplication(m) |
PreviewTargetURL |
|
|
| 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 |
|
|
| 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) |
PreviewUserGroups |
|
|
| The Currently in preview context UserGroup assignments are used for: content components, shipping rules and payment methods. | true | false | true | none | CurrentChannel (m) |
PreviewCustomerSegmentBOs |
|
|
| The | true | false | true | none | none |
PreviewDisplayDevice |
|
|
| 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) |
PreviewPromotions |
|
|
| The | false | true | true | none | none |
PreviewCampaigns |
|
|
| The | false | true | true | none | none |
PreviewABTestGroups |
|
|
| The | false | true | true | none | none |
CatalogCategoryOnlineIgnoredAttribute |
|
|
| 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 |
|
|
| 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 |
|
|
| Tells the application that evaluates this setting whether a product that is not available should be available for checkout or not. | false | true | true | false | none |
ProductInventoryIgnoredAttribute |
|
|
| 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 |
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.
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"
).
The following three tables list all pipelets of bc_preview available in this release:
Pipelet Name | Description | Configuration | In Properties | Out Properties | Has Error Connector |
---|---|---|---|---|---|
CreatePreviewConfigurationAttributeContext | Creates a
| none | ConfigurationAttributeMap: | PreviewConfigurationAttributeContext: | no |
Pipelet Name | Description | Configuration | In Properties | 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: | PreviewConfigurationAttributeID: | PreviewConfigurationAttribute: | no |
GetPreviewConfigurationAttributeID | Returns a PreviewConfigurationAttributeID value from a given (PreviewConfiguration)AttributeSet in combination with an AttributeSetValue (which is the enum value) | AttributeSet: | none | PreviewConfigurationAttributeID: | no |
DeselectPreviewConfigurationAttribute | Deselects all selected values of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
ResetPreviewConfigurationAttribute | Resets a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
SetSelectedPreviewConfigurationAttributeValue | Sets one attribute value of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
SetSelectedPreviewConfigurationAttributeValues | Sets several attribute values of a | AttributeSet: | PreviewConfigurationAttributeID: | none | no |
GetSelectedPreviewConfigurationAttributeValueObjects | Get all selected (attribute) values of a preview configuration attribute in the context of the given | AttributeSet: | PreviewConfigurationAttributeID: | ValueObjects: | no |
Pipelet Name | Description | Configuration | In Properties | Out Properties | Has Error Connector |
---|---|---|---|---|---|
CreatePreviewContext | Creates a new | none | ID: | PreviewContextBO: | no |
GetPreviewContextByID | Returns the found | ID: | ID: | PreviewContextBO: | yes |
RemovePreviewContext | Removes the given | none | PreviewContextBO: | none | no |
CreateFullSitePreviewContextBO | From a given | none | PreviewContextBO: | FullSitePreviewContextBO: | yes |
CopyIntersectValues | This pipelet copies attribute settings from one | none | PreviewContextBOSource: | none | no |
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:
The present concept describes how this can be done.
PCA | PreviewConfigurationAttribute - refers to the interface |
---|---|
PCAV | PreviewConfigurationAttributeValue - refers to the interface |
PrevCon | PreviewContextBO - refers to the interface |
The following picture outlines the schematic overview:
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
.
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).
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.
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:
PCA
is selected using a boolean valuePCA
is updated with a collection of values that is part of the PCA's
value domainPCA
is only updated with one value that is also part of the PCA's
value domainPCA - PreviewTargetURL
DisablePreviewForPastDates
is enabled.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.
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
.
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
).
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.
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.
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.
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.
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.
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.
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.
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.
The full site preview function allows to open a complete separate browser window and view the storefront with the preview settings determined in the Design View.
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:
PreviewContextPO
object by using PreviewContextMgr
PreviewContextPO
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.
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.
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.
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:
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.
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:
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)
PREVIEWCONTEXT
with lastmodified < ComputedDate
.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.
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.
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.
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.