ContentConnect

The reference project and cartridges were updated to the MFRA (Mobile First Reference Architecture) version v2.1.0 with this version of the ContentConnect module. In order to migrate to the new MFRA version the affected components have to be updated as follows:

The cartridges int_firstspirit_cms_mfra and int_firstspirit_cms_core have to be updated within the WebDAV directory.

The following custom regex needs to be appended to the output channel of the preview_generation format template:

$-- Remove tracking consent popup --$
<!-- CMS-REGEX-PATTERN-START -->
    regex-match="<span.*?class=".*?tracking-consent.*?"(?s).*?><\/span>"
    regex-value=""
<!-- CMS-REGEX-PATTERN-END -->

The version 2.48.0 fixes a typo in the reference name of the product page folder within the page creation. As a result, creating product pages after updating to this version might create a second page folder for product pages. Since this doesn’t interfere with any functionality whatsoever, a migration is not necessary.

However, if a migration is still needed it will be sufficient to move all of the product pages of the old page folder (with the reference name containing the typo) to the newly created page folder (with the correct reference name).

The version 2.48.0 introduces the new feature Apache Velocity code rendering. It provides the functionality to render Velocity code within the preview of pages that are managed by FirstSpirit.

Further information about Velocity rendering can be found in the chapters Preview and Category detail pages of the german documentation.

In order to make use of the CommerceCloud Script-API you need to provide a Storefront controller that performs the rendering of the velocity code. An example implementation of such a Storefront controller is contained within the module distribution at: /cartridge/controllers/Content.js

The Storefront controller that is responsible for Velocity rendering has to strictly adhere to the following traits:

The name of the controller and the method can be chosen freely because they are managed with an input component within FirstSpirit.

The ContentConnect Preview finds all velocity code fragments of a page and sends them to the Storefront controller. Therefore it needs some way of finding the Velocity code fragments which means you have to provide HTML comments with this predefined syntax:

<!-- CMS-VELOCITY-{ID}-START -->
 	{Velocity code}
<!-- CMS-VELOCITY-{ID}-END -->

For more information about the Velocity rendering markings and the configuration of the Storefront controller head to chapter Category detail pages of the german documentation.

The new version of the ContentConnect module extends the available API.

The class ProductManager now contains the additional methods getTemplateMappingCategory and getTemplateMappingProduct. Those methods grant access to the template mapping configurations of categories and products which can be configured within the project component. Due to the newly added methods the CategoryTemplateMapping class became obsolete, is marked as deprecated, and the new TemplateMapping class will serve as a replacement.

With this version of the ContentConnect module the cartridge was split into the following three cartridges:

A migration to the new cartridges is not necessary because no additional functionality was introduced with this version of the module. In case of migrating to the new cartridges the core cartridge has to be added to the cartridge path of the site in addition to the architecture-dependent cartridge (either MobileFirst reference architecture cartridge or SiteGenesis cartridge).

This version of the ContentConnect module also adds support for the version 2.0 of the Mobile First Reference Architecture (MFRA). The StarterPackage won’t be backward compatible to older versions of the MFRA from now on.

This version contains a renewed StarterPackage. The reference project and the templates in the cartridge are now based on the new MobileFirst Reference Architecture.

The documentation of the ContentConnect module has also been rewritten. It has a strong relation to the new StarterPackage and focuses on the implementation of specific use cases.

The new version of the ContentConnect module includes the ContentConnect Preview Proxy. The ContentConnect Preview Proxy provides means to cope with problems caused by Cross-origin requests while loading external resources within the preview.

For further information on how to configure and use the ContentConnect Preview Proxy head to the section ContentConnect Preview Proxy of the german documentation. The english documentation will contain the new section ContentConnect Preview Proxy in the near future.

By adding the ContentConnect Preview Proxy to the ContentConnect web component the web.xml has been extended by two entries regarding the proxy. The web.xml will be updated automatically during the update of the module, as long as the file hasn’t been edited previously. In this case the file will remain unchanged after the update and the following entries have to be added manually to the web.xml of the Preview and the ContentCreator:

<servlet>
   <servlet-name>ContentConnectPreviewProxy</servlet-name>
   <servlet-class>com.espirit.moddev.demandware.preview.proxy.ProxyServlet</servlet-class>
   <load-on-startup>0</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>ContentConnectPreviewProxy</servlet-name>
   <url-pattern>/proxy/*</url-pattern>
</servlet-mapping>

For further information on the web components head to the chapter Adding web components of the documentation.

The new version of the ContentConnect module introduces the Content cleanup feature and extends the available API. The Content cleanup feature allows for automatic cleanup of obsolete content assets and slot configurations that were managed by FirstSpirit. In order to make use of this feature follow all of the instructions below.

Several different methods were added to the API. The SlotConfigurationManager interface now contains the two new methods deleteSlotConfigurations and searchSlotConfigurations. The class SearchRequest was added to the API to use the searchSlotConfigurations method. The SearchRequest class represents a generic OCAPI search requests by providing a Query, which was also added to the API.

Besides that, the deleteContentAssets method was added to the LibraryManager interface. Further information about the specific usage of the ContentConnect API can be found within the Javadoc documentation.

This version update adds the ContentConnect Preview Filter to the module. It increases template code readability, replaces JSP-logic and reduces error-proneness with large pages.

There are several things that need to be adjusted in order to use the new ContentConnect Preview Filter. That includes adjustments within page templates, format templates and project settings. Additionally, the web componenent of the ContentConnect Preview filter needs to be configured.

A detailed description of all the adjustments mentioned above can be found in chapter 8 of the documentation.

The category report now also includes hidden categories. This feature can be enabled and disabled by a new filter in the report.

Due to this new feature, the Password parameter in the project app configuration is now mandatory and must not be empty.

Furthermore, the client id needs the permission to perform GET requests on the following DataAPI ressources:

The template Preview Generation has been updated:

Old. 

$CMS_SET(set_replaceTracker, "(<!-- Demandware Analytics)((.|[\\t\\n\\r])*)(</script>)")$

New. 

$CMS_SET(set_replaceTracker, "(<!-- Demandware Analytics)(?s:.)*(</script>)")$

This update prevents a possible Stackoverflow exception. It is highly recommended to perform this update in existing projects manually as well.

Demandware was renamed to Salesforce Commerce Cloud. Therefore the module got a new name as well: ContentConnect for Salesforce Commerce Cloud

ContentConnect supports the usage of the Content Integration API. Chapter 8 of the documentation describes the integration with FirstSpirit.

Besides the steps described in the documentation, further adjustments are necessary to use the Content Integration API in existing projects.

First, in the format template preview_generation the following code snippet should be moved to the top of the enclosing JSP scriptlet:

$-- Inject CMS preview content: Replace placeholder with actual CMS content --$
$CMS_FOR(for_item, [0..stringToReplace.size-1])$
    html = html.replaceFirst(
        "$CMS_VALUE(stringToReplace[for_item])$",
        "$CMS_VALUE(stringToInsert[for_item].toString().quoteJS())$");
$CMS_END_FOR$

Second, the new template include_html must be created manually. Use the following content:

//!Beanshell

import java.net.URL;
import java.net.URLConnection;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.MalformedURLException;

String includeURL = gc.getVariableValue("includeURL").toString();
String name = gc.getVariableValue("name").toString();
String password = gc.getVariableValue("password").toString();
String isProtected = gc.getVariableValue("isProtected").toString();
String html = "";

includeURL = includeURL.replaceAll(" ","%20");
URL url = new URL(includeURL);
URLConnection urlConnection = url.openConnection();

if (isProtected.equals("true")){
    import org.apache.commons.codec.binary.Base64;

    String authString = name + ":" + password;
    byte[] authEncBytes = Base64.encodeBase64(authString.getBytes());
    String authStringEnc = new String(authEncBytes);

    urlConnection.setRequestProperty("Authorization", "Basic " + authStringEnc);
}

InputStream is = urlConnection.getInputStream();
InputStreamReader isr = new InputStreamReader(is);

int numCharsRead;
char[] charArray = new char[1024];
StringBuffer sb = new StringBuffer();
while ((numCharsRead = isr.read(charArray)) > 0) {
    sb.append(charArray, 0, numCharsRead);
}
html = sb.toString();
html = html.replaceAll("\\$", "$");

return(html);

With the new version it is possible to configure more than one FirstSpirit page template for detail pages for categories. Therefore the cartridge needs to be updated in exisitng projects.

The ContentConnect API has been extended with this version of the module.

First, the package com.espirit.moddev.demandware.manangers has been extended. Besides ProductManager, it now contains the interfaces LibraryManager and SlotConfigurationManager. Using these interfaces one can delete content assets, library folders and slot configurations.

Another important change is the introduction of the package com.espirit.moddev.demandware.factories. This package contains the class ManagerFactory that can be used to create instances of the interfaces mentioned above. If the ContentConnect module is installed, ManagerFactory will be accessible server-wide and can therefore be used e.g. in BeanShell scripts, workflows or schedule entries.

Analogous to ManagerFactory, XmlCollectorFactory provides means to create instances of the interface XmlCollector.

ManagerFactory as well as XmlCollectorFactory used to be FirstSpirit executables in previous versions of the ContentConnect module. These executables are still present, but their implementing classes have been renamed to ManagerFactoryExecutable and XmlCollectorFactoryExecutable. Despite this change, adjustments in existing projects are not necessary, since executables are accessed by their name. The names of the two executables haven’t been changed.

More information about the ContentConnect API can be found in the provided Javadoc documentation.

The ContentConnect module now allows to easily create detail pages for products and categories. For this purpose a button is shown on every report item, that opens the form of a project specific page template. A detail page will be based on this template and the form input.

Figure 2. Anlegen einer Detailseite

Figure 3. Dialog zum Anlegen einer Detailseite

DemandwareConnect 1.5.0 contains several changes and new features. Therefore it is necessary to perform some migration steps if a prior version of the module is installed. These steps are listed below and should be executed in the same order they are listed:

After the installation of the new module some templates need to be adjusted.

If the scripts CreateProductManager (reference name "createproductmanager") and CreateXmlCollector (reference name "createxmlcollector") do not exist, they need to be created using the stated reference names and the following contents:

CreateProductManager. 

#!executable-class
ManagerFactory

CreateXmlCollector. 

#!executable-class
XmlCollectorFactory

The initialization of the xml collectors needs to be adjusted in the project settings template. Furthermore, the instantiation of Connector must be replaced because now the interface ProductManager must be used to request product information in templates.

Xml collector for the content library:

old. 

$CMS_SET(ps_xmlCollector,class("com.espirit.moddev.demandware.xml.DemandwareXmlCollector").newInstance())$

new. 

$CMS_RENDER(script:"createxmlcollector",variableName:"ps_xmlCollector")$

Xml collector for the content slot configuration:

old. 

$CMS_SET(ps_xmlCollectorContentSlot,class("com.espirit.moddev.demandware.xml.DemandwareXmlCollector").newInstance(false))$

new. 

$CMS_RENDER(script:"createxmlcollector", variableName:"ps_xmlCollectorContentSlot", createLibraryNode:false)$

Object for requesting product information:

old. 

$CMS_SET(ps_DWRconnector,class("com.espirit.moddev.demandware.products.Connector").create(#global))$

new. 

$CMS_RENDER(script:"createproductmanager", variableName:"ps_productManager")$

Some components in the module have been renamed. Therefore all occurrences of FSDWC_ need to be replaced by DemandwareConnect_. The product drop handler is one of the components that have been renamed.

The interface ProductManager is incompatible with the public interface of the formerly used class Connector. Therefore, the retrieval of product information must be adjusted:

queryProduct(old). 

ps_DWRconnector.queryProduct(for_product.id)

loadProduct (new). 

ps_productManager.loadProduct(for_product.id)

Besides the replacement of Connector by ProductManager, the interfaces Product and Category have been modified as well. Corresponding template changes might be necessary.