Migrating to an SAP Commerce Cloud Responsive Storefront
26 min read
The release of SAP Commerce version 5.4 introduced a new B2C Responsive Storefront, followed by a new B2B Responsive Storefront in version 6.0. With both of the main accelerator storefronts responsive in the 6.4 release the mobile-related elements--which were used in the old approach of building storefronts-were completely removed. This article describes the process of migrating a B2C storefront created prior to 5.4.x to the responsive storefront that shipped with SAP Commerce version 6.7.x.
As outlined in Choosing Which Storefront to Use for Your SAP Commerce Cloud Solution, there are now more options when it comes to storefronts. If you are planning to migrate from a legacy storefront you might want to determine whether the responsive storefront is the best fit for your requirements.
Table of Contents
SAP Commerce 6.0 introduced a new way of working with responsive storefronts. As opposed to legacy approach that was serving completely different pages, stylesheets and scripts based on what device was used (mobile or desktop) the new approach utilizes a new frameworks and CSS features that allows using one single point-of-truth and reuse the same files.
The legacy approach caused a lot of additional work to keep both the desktop and mobile channels up to date with new features, since every small change to one channel would have to be mirrored in the second one including files, scripts and CSS styles. This approach was very time consuming, both during development and maintenance.
The impact on migrating to the Responsive Storefront will vary depending on which SAP Commerce version is being used as the source. This is due to technical changes between older and newer versions of the platform containing different base libraries' versions, pre-processors, CMS Components changes, and deprecations or removals. The impact will be heavier as more custom code is written and unfortunately some of out-of-the-box components used in projects will need to be taken care of during the migration process.
Next, a pure responsive storefront should be generated in your target version and compare it to the pure version of Accelerator in your source version. This may help identify similarities and components that can easily be reused with no additional work. This will result in a general hint of the required effort on top of migrating your existing customizations.
JSPs, tags and fragments
The main concern for this part of migration is basically all custom work done in the project as opposed to out of the box, but another layer of complexity is likely to come up if the source version used the old architecture of split themes for mobile and desktop.
As long as no change was performed to out-of-the-box components during project customization, this should not be an issue, but keep in mind that it's not rare for those components to get altered by project teams - in such case the migration becomes much more difficult, since all. changes have to be detected and manually mirrored in the new responsive storefront.
For every custom JSP and tag file that are present in storefront extension, assume that there is additional work needed rather than just copying it over to the new storefront. This is due to changes in out-of-the-box stylesheets. The major factor here is the legacy mobile/desktop, current responsive approach, and other general changes in the styling of out of the box components that may interfere with custom styles.
Keep in mind that storefront migration also affects storefront controllers. Codebase changes in
out-of-the-box platform throughout different versions may cause various problems when combined with custom
controllers, which reuse or extend the platform code. Some customer solutions contain heavily customized
controllers, adding complex logic that sometimes might not be trivial at all to migrate or reflect in new
During the analysis and estimation one should identify all custom controllers, their dependencies to the platform controllers and impact on storefront components behavior (including JSPs, tags and fragments) since it is a common approach to steer the behavior based on controllers behavior.
The key point is that some of the custom controllers may limit or even completely rule out using the new accelerator code, which might require a lot of work to fix properly.
SAP Commerce version 6.1 introduced a new way to handle styling of pages. Instead of using plain old CSS the platform now offers a LESS pre-processor that eases the work with styling. Even though this will lead to less maintenance in the long term, such an improvement brings another level of complexity and possible issues to the migration process.
It is very common for a project to only use plain CSS stylesheets and we highly recommend you port them to utilize the LESS approach. However, this requires a lot of work and if the situation requires a rapid migration then the old .css files needs to work well with the new approach if migrated to correct folder structure. The reason behind recommending and moving all styles to LESS files is that this allows future development and migrations to benefit from the approach and comply with SAP Commerce platform standards.
This is probably the most complicated and costly part of the migration process, since many existing components have been reworked, deprecated, or deleted over different versions. This is a concern for the storefront experience itself, but in some cases it will only affects the management of those components in SmartEdit.
The main change regarding CMS components is the navigation itself, where the whole structure was reworked and different components should be used in current versions of the platform than was previously used. This impacts the storefront experience and editing the navigation in CMSCockpit or SmartEdit. If your project contained simple navigation that properly reused out-of-the-box navigation and contained no custom work, then this part will have little impact. Unfortunately, the majority of projects have custom code and logic in the navigation, which adds more complexity and increases the impact. If you choose to copy-over the navigation from the source version of the project being migrated, then it will most likely result in non-editable content.
Given the constant development for SmartEdit it is hard to provide an estimate of the impact it will have on your project. The product documentation for SmartEdit contains support for each of the existing or historical components (for example here is the page for 1808 components). Keep in mind that some of the existing components (such as RotatingImagesComponent) were dropped and it is pretty easy to migrate the storefront part by copying over the JSP file and stylesheets, but implementing such a component in SmartEdit is not trivial. See the sections on customization for the page.
Migration how to - background
Given the significant differences between how the legacy storefronts and the responsive storefront are developed, as well as the various levels of customizations for each particular project, there is no migration tool for storefronts. In the sections below we provide a description of the steps you can take to perform a storefront migration between an SAP Commerce storefront prior to the introduction of the responsive storefront (i.e. 5.3.x) and a version with mobile-related elements removed (i.e. 6.7.x). This is described using the example of a few storefront features implemented for purpose of this article.
Legacy Storefront Setup
This section describes, the example storefront features which were implemented in an out-of-the-box B2C Accelerator for SAP Commerce 126.96.36.199. The Following section describes the process of migrating these features to newer platform version. The implemented features were:
- New CMS page template and new CMS page.
- New CMSParagraphComponents and SimpleBannerComponent added as the content for the created page.
- Custom tag with clickable toggle element and text message.
- Custom CSS stylesheets with differences between mobile and desktop UI experiences.
These items were implemented separately for the mobile and desktop UI experiences. The steps to implement these features were:
- Generating a new
examplemodule by using
- Adding elements which will be used for desktop UI experience:
Adding IMPEX containing new page template, content page, CMS components, content slots and media items
examplePage.jspfile representing desktop page view to
Adding custom tag file
examplestorefront\web\webroot\WEB-INF\tags\desktop\template\compressible\css.tagfile to embed newly created CSS file
- Adding elements which will be used for mobile UI experience:
Importing IMPEX containing new page template, content page, CMS components, content slots and media items
examplePage.jspfile representing mobile page view to
Adding custom tag file
<%@ tag body-content=
<%@ taglib prefix=
examplestorefront\web\webroot\WEB-INF\tags\mobile\template\compressible\css.tagfile to embed newly created CSS file
base_xx.propertieslanguage files in
examplestorefront\web\webroot\WEB-INF\messagesdirectory with custom messages
After a platform build and importing IMPEX resources, the mobile/desktop UI experience storefronts are accessible when visiting the site using given device. The images below show what the pages look like on both the mobile and desktop UI experiences:
The content layout on mobile page is different than the layout on desktop page – in this example on small screens there is one column of text and on larger screens there are two columns of text. The content is also different – in this case the displayed banner is different depending on the UI experience. There are also differences in applied styles - different toggle element and paragraph paddings.
General Migration Approach
Because of differences in structure of storefront extensions between platform versions 5.3.x and 6.7.x, the general approach to migrating the storefront can be divided into a few main steps:
- Generating new storefront extension by running
ant extgentask in the new platform version.
- Basing on the analysis from first point, the custom files and resources have to be extracted, placed in the respective directories of new generated storefront extension, and adjusted to requirements of new responsive UI experience if needed.
Migration of Implemented Features
This section describes the process of migrating the previously described custom storefront features. As mentioned before, the storefront is migrated from platform 5.3.x version to 6.7.x version. To perform the migration of implemented custom featured following steps have to be performed:
- Generating a new set of custom extensions basing on default B2C Accelerator by
Creating new custom theme
exampletheme, basing on existing
alphatheme. For more information, see Creating New Themes.
- Because the responsive storefront does not require creating separate CMS pages for different UI
experiences, only one CMS page has to be migrated. In this case, the mobile-related CMS content does
not need to be included and the remaining desktop-related content is to be taken as basis for
creating CMS content for responsive storefront. To enable responsiveness few modifications have to
be added to these IMPEX scripts.
Firstly instead of using SimpleBannerComponent a new SimpleResponsiveBannerComponent can be used. This component allows to map media files to media formats, which are specific to a responsive UI experience. Secondly, a mediaFormat attribute has to be specified in Media components. Last change in IMPEX is to add new MediaContainer component and add both banner images to it. These three changes are shown in code block below.
As there is only one CMS page to migrate, also only one JSP view has to be migrated to the target version. This can be done by copying
examplestorefront\web\webroot\WEB-INF\views\responsive\pages\examplefolder in new platform. Additionally, some changes have to be made to the file itself. Instead of using
span-24 CSSclasses, the Bootstrap grid system should be used. This provides the responsive behaviour of page elements. Also values of
taglibelements have to be adjusted to point to responsive directories. If there were more custom JSP views for either pages or CMS components, all of them have to be verified and manually adjusted to enable responsive behaviour. The code block below shows how the original
examplePage.jspwas modified to work as a responsive page:
- Copying file custom
examplestorefront\web\webroot\WEB-INF\tags\responsive\examplefolder in the target versionof your code. In this case no additional modifications are needed, as both original tags from mobile and desktop UI experiences are identical. If these tags were different, manual adjustments would be needed to provide responsiveness. If there were any other custom tags, these should be also copied to responsive folder and adjusted manually if needed.
Creating a new
example.lessfile in your target code's
examplestorefront\web\webroot\WEB-INF\_ui-src\responsive\themes\exampletheme\lessfolder (custom generated theme directory). Because the original
example.cssfiles in mobile and desktop folders are not identical, so there is a need to combine these two files into one stylesheet that provides the original styling. In this case, the recommended practice is to use features provided by LESS preprocessor, such as declaring variables or chaining inner selectors. Variables should be declared in separate file, for example
examplestorefront\web\webroot\WEB-INF\_ui-src\responsive\themes\exampletheme\less\theme-variables.less. Additionally media queries should be used when different views require different styling. The LESS variables declarations and new
example.lessfile are shown below.
Additionally the new LESS files must be imported by updating custom theme
Copying custom messages from old platform to
base_xx.propertieslanguage files in
examplestorefront\web\webroot\WEB-INF\messagesdirectory in new platform.
example.toggle = Hide/show text
The new responsive website build process requires generating
_ui folder from
_ui-src folder. This can be done
examplestorefront_compileuisrc task. For more information,
see Responsive Website Build Process.
After platform build and importing IMPEX resources, the responsive storefronts are accessible when the site is visited. The images below show what the migrated pages now look like on mobile and desktop screens.
The exploration tests should be performed to verify if the storefront migration was successful. During the tests the page should be accessed by using devices in different screen sizes. The browser developer tools can be used to check how the page looks on different devices. However, if it's possible the page should be checked using phone, tablet, or other, to confirm that the styles and scripts are working correctly on the particular device. Also the behaviour of elements should be tested and the appearance should be examined to confirm that the scripts and styling is properly migrated and adjusted to responsive storefront requirements.