AddOn Concept ,Creating AddOns,Installing an AddOn for a Specific Storefront,Customizing the Storefront using an AddOn

https://help.sap.com/viewer/b490bb4e85bc42a7aa09d513d0bcb18e/1808/en-US/8adc7ca3866910148ddfe860464f0fc4.html


AddOn Concept

AddOns are built on top of the existing SAP Commerce to extend the functionality of the SAP Commerce Accelerator. AddOns are a type of extension that allow you to add front-end files (such JSP, HTML, CSS, and JavaScript files, as well as images) from within your own AddOn, instead of modifying the storefront front-end files directly.
The overall extensibility of SAP Commerce Accelerator is improved in the following ways:
  • You can generate your facade Data Transfer Objects (DTOs) and extend them, even if they are not defined in your own AddOn.
  • You can plug populators into existing converters without having to redefine them.
  • Some facades and services have been refactored so that they can be easily plugged in and their behavior can be easily modified.
For more information on extensions, see Extension Concept.

Overview

SAP Commerce Accelerator is built on an extensive framework that includes a template for storefront implementation. AddOns and extensions provide a well-defined infrastructure for third party developers to plug in their own functionality.
Using AddOns, you can extend the functionality of Commerce Accelerator without editing the core code base. The core code base in this context means the Commerce Platform, and all additional extensions delivered with Commerce Accelerator. An AddOn is a regular extension that may, or may not, provide additional front-end components to Commerce Accelerator.
Creating Extensions
When creating extensions (including AddOns), it is a good idea to keep the logic and storefront-related features in separate extensions. That is why extensions are organized into the following groups:
  • Accelerator project extensions
  • Accelerator cockpit extensions
  • Accelerator sample and test data
  • SAP Commerce storefront API extensions

AddOn Architecture

An AddOn is a regular SAP Commerce extension that is configured using the extensioninfo.xml file, located in the root folder of the AddOn. Additionally, the storefront extension that is extended by an AddOn has to reference this AddOn in the extensioninfo.xml file. The structure of this file is exactly the same as any regular extension. For more information about this file, see extensioninfo.xml.
Extensibility of the Framework
The diagram below illustrates the three-layer model of the extensible framework of Commerce Accelerator:
At the bottom is the Service layer, which includes fine-grained business methods, such as the ones responsible for adding promotions to a cart, or for calculating the total value of the cart. These services expose the data model, which persists in the database.
On top of the Service layer, there are facades, which implement specific business use-cases, such as adding a product to a cart, placing an order, or searching for a product. The facades expose the Data Transfer Objects (DTOs), which are completely independent from the underlying storage technology. There may be a one-to-one mapping of the model (such as store products), but there may also be a subset of the model, or aggregated models. The DTOs are not always stored in the database. An example of this is the Solr objects, which are stored in the Solr index.
The converters delegate to populators to convert the DTOs back and forth to models. For example, a product that has basic attributes, such as name, title, and description, can also have classification attributes. Therefore, you might have two populators, one for the basic attributes, and one for the classification attributes.
The facade layer, including the DTOs, represents the SAP Commerce OmniCommerce Connect. This is a business API, and the foundation for the web services.
On the top layer, the Controllers take the DTOs and expose them to the view. This is done using the Spring Model View Controller (MVC), which replaces all the facades, services, and controllers.
Extensibility of the Front-End
One example of extending the front-end is to enable customer feedback on your storefront. In this scenario, when a customer provides feedback, or rates a certain product, the system would automatically create a Customer Service Cockpit ticket for a customer service representative to review.

The AddOn Approach

The AddOn concept aims at extending the Accelerator storefront without touching its core code base. For example, you could implement customer feedback functionality on your storefront without editing the source code. Instead, you would plug in all the functionality from within your AddOn.
Continuing with this example, the AddOn would have an additional folder called acceleratoraddon, and the structure of the folders within it mirrors the structure of the folders containing the front-end components of a regular extension, as follows:
Figure: acceleratoraddon folder structure
In this example, the web folder contains both the src and the webroot subdirectories. After putting all the components you want to add into the proper folders, you need to run the following command on your system: ant build<Enter>.
The system automatically copies the files to the target storefront extension during the build phase, and creates two additional folders containing the imported content:
After the build phase finishes, the target extension contains the following new folders:
  • web/addonsrc, which contains the source code for each installed AddOn. This gets compiled automatically.
  • web/webroot/WEB-INF/addons, which contains all the front-end components, such as images, JSP files, HTML files, and TAG files.
All the contents of these folders are processed automatically during the development phase. By default, this mechanism is disabled on the production systems so as not to impact the performance of the system. This is because the process continuously checks if the contents of the folders have changed.

Benefits of the AddOn Approach

The benefits of the AddOn Concept approach are as follows:
  • AddOn files are kept separate from the rest of the front-end files.
  • When you upgrade the Accelerator, it will not overwrite your files.
  • You can easily remove your AddOns without refactoring the code of your whole extension.
Improved Overall Extensibility
The AddOn approach makes it easier to modify the exposed data model. For example, if you want to add a new attribute to a product , you do not have to subclass the DTO. Instead, you can plug in a new populator, which is responsible for adding the new attribute:
Additionally, you can modify multiple extensions at once. Previously, due to Java restrictions, you could only modify the subclass once. Now, you can plug in new data from every extension using a new XML descriptor to generate the DTOs. Each extension can provide such a descriptor. All definitions are merged, so you can add attributes to existing DTOs and fill your attributes with pluggable populators. As a result, you can extend an existing API without needing to replace anything.
The following is an example of an XML descriptor:
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="beans.xsd">
 
 <bean class="de.hybris.platform.commercefacades.product.data.ProductData">
  <property name="weight" type="int" />
  <property name="instruction" type="String" />
  <property name="additionalImage" 
       type="de.hybris.platform.commercefacades.product.data.ImageData" />
 </bean>
 
 <enum class="de.hybris.platform.commercefacades.product.ProductOption">
  <value>DIMENSIONS</value>
  <value>MINIMAL</value>
 </enum>
</beans>
Similarly to the item.xml file, the definitions in the beans.xml file are merged automatically. In the example above, the ProductData file is not part of our example extension, but it is extended from the commerceservices extension. That means that during this process, you extended the API because you modified the data model. You do not need to replace the facade in this instance. All you need to do is plug in the populator from your extension, and it can be done multiple times.

AddOns Best Practices

We recommend that you put as much logic into your AddOns as possible. The advantage of this is that whenever you need to upgrade your Accelerator code base, you do not need to merge the changes manually. By having the logic put into the AddOns, you can build a library of self-contained, reusable components that you can use for your future projects.

PreviousNext

Creating AddOns

Learn how to create an empty AddOn, which is the first step in creating your own custom AddOns.
AddOns allow you to extend or override storefront extensions without having to modify the extensions directly. In addition to simply using the preconfigured AddOns provided by SAP, you can create your own custom AddOns. To do so you create a blank AddOn, install it, and then modify its logic.
To create a blank AddOn.
  1. In the command prompt window or Terminal, navigate to the <HYBRIS_HOME>/hybris/bin/platform folder.
  2. Run the appropriate command:
    • setantenv.bat on Microsoft Windows systems.
    • . ./setantenv.sh on Unix-related systems (such as Linux or Mac OS).
  3. Run the following command to create a new extension named myextension. The new extension is created under<HYBRIS_HOME>/hybris/bin/custom.
    ant extgen -Dinput.template=yaddon -Dinput.name=myextension -Dinput.package=com.myapp.myextension
  4. Open the <HYBRIS_HOME>/hybris/config/localextensions.xml file and add your new extension:
    <extension name="myextension" />

Copying Files Between an AddOn and a Target Storefront

During the build process, the system copies files from the acceleratoraddon folder to the web folder of the target extension.
AddOns allow you to extend storefront extensions without having to modify the extensions directly. AddOn extensions are similar to regular extensions, but they allow you to add front-end related items (such as JSP files, CSS files, and images) without requiring you to build the platform. You can also add new Java code to the target extension, but that requires building the platform. The front-end items are stored in the acceleratoraddon folder of an AddOn.
The structure within the acceleratoraddon folder mirrors the folder structure within the web folder, which contains the front-end components of a regular extension.

Folder Structure

During the build process, the contents of the following folders are copied to the target extension:
FolderDescriptionTarget Folder
<addon_name>/acceleratoraddon/web/webroot/_ui
This folder contains static resources, such as CSS css files, JS files, and images.
<yacceleratorstorefront>/web/webroot/_ui/addons/<addon_name>
<addon_name>/acceleratoraddon/web/webroot/WEB-INF/<folder/subfolder/resource>
These folders contain TAG files, JSP files, TXT files, and so on.
<yacceleratorstorefront>/web/webroot/WEB-INF/<folder/addons/addon_name/subfolder/resource>
<addon_name>/acceleratoraddon/web/src
The subfolders of the srcfolder contains the web application Java source code.
<yacceleratorstorefront>/web/addonsrc/<addon_name>

Copying Files

During the build process, there is a build callback for copying the files after the yacceleratorstorefront is compiled. This occurs as follows:
  1. The system scans for every extension that has a specific acceleratoraddon folder. Marker folders are defined as follows:
    ${extension-path}/acceleratoraddon/web/webroot/_ui
${extension-path}/acceleratoraddon/web/webroot/WEB-INF
  2. For each AddOn that is found, the system identifies the target extension.
  3. For each resource that is found in the acceleratoraddon folder, the system copies the contents to the target extension.

Deleting Copied Files

The system uses the ant sync task to keep the contents of the acceleratoraddon up to date with the contents of counterpart storefront extensions.
The AddOn directories in all storefront extensions that are defined in the localextensions.xml file are cleaned up with theant clean command when building the Commerce Platform.

Installing an AddOn for a Specific Storefront

The addoninstall tool allows you to configure an AddOn for a storefront. It also adds the AddOn to the extensioninfo.xmlfile of the storefront, and generates the relevant project.properties file for the AddOn.

The addoninstall Tool

The following table lists the parameters of the addoninstall tool:
ParameterNotes
addonnamesThis parameter is mandatory. If more than one AddOn name is specified, the names must be separated by commas. If you do not include the addonnamesparameter when you run the addoninstall command, you are asked to provide it.
addonStorefront.<storefrontTemplateName>This parameter is used to indicate which storefronts you are installing the AddOn for. If more than one storefront is specified, the storefront names must be separated by commas. The <storefrontTemplateName> variable indicates the storefront template you wish to use for storefront generation. By default, the two possible values are yacceleratorstorefront andyb2bacceleratorstorefront.
The ant addoninstall command has the following format:
ant addoninstall -Daddonnames="AddOnName1,AddOnName2" -DaddonStorefront.<storefrontTemplateName>="Storefront1,Storefront2"
The following is an example of the ant addoninstall command, where two AddOns (NewAddOn1 and NewAddOn2) are installed for B2CStorefront1 and B2CStorefront2, as well as for B2BStorefront1 and B2BStorefront2:
ant addoninstall -Daddonnames="NewAddOn1,NewAddOn2" -DaddonStorefront.yacceleratorstorefront="B2CStorefront1,B2CStorefront2" -DaddonStorefront.yb2bacceleratorstorefront="B2BStorefront1,B2BStorefront2"

The project.properties.template File

When you run the ant addoninstall command, the project.properties file for the AddOn is generated automatically. This is done using the project.properties.template file. Note that when you run the ant addoninstall command, theproject.properties.template file overwrites the contents of the project.properties file of the AddOn.
When generating the project.properties file, the addoninstall tool executes the following steps:
  • Deletes the old project.properties file.
  • Generates the new project.properties file from the project.properties.template file.
  • Adds a relative import file reference in the yacceleratorstorefront/web/webroot/WEB-INF/_ui-src/responsive/lib/ybase-x.x.x/less/addons.less file if such reference does not already exist and the AddOn’s_ui-src/reponsive/less folder contains an <AddOn Name>.less file. For more information on LESS support for AddOns, see Responsive Website Build Process
  • Replaces the storefront name with the following line in the project.properties file:
    <storefrontTemplateName>.additionalWebSpringConfigs.<AddOnName>=classpath:/<AddOnName>/web/spring/<AddOnName>-web-spring.xml

Configuring the AddOn Storefront Properties

When generating a new project.properties file, you can replace the addonStorefront.<storefrontTemplateName>property, or you can delete it, as described in the following sections.
Replacing the AddOn Storefront Properties
You can replace the default storefront properites by using the following parameter when you run the ant addoninstallcommand: addonStorefront.<storefrontTemplateName>=Storefront1,Storefront2.
For example, the default storefront properties for the B2C Accelerator appear in the project.properties file as follows:
yacceleratorstorefront.additionalWebSpringConfigs.<AddOnName>=classpath:/<AddOnName>/web/spring/<AddOnName>-web-spring.xml
If you specify the storefront parameters asaddonStorefront.yacceleratorstorefront=B2CStorefront1,B2CStorefront2, the default line above is replaced in theproject.properties file with the following:
B2CStorefront1.additionalWebSpringConfigs.<AddOnName>=classpath:/<AddOnName>/web/spring/<AddOnName>-web-spring.xml
B2CStorefront2.additionalWebSpringConfigs.<AddOnName>=classpath:/<AddOnName>/web/spring/<AddOnName>-web-spring.xml
Deleting the AddOn Storefront Properties
If you set the storefront parameter addonStorefront.yacceleratorstorefront=blank, the following property is deleted from the project.properties file:
yacceleratorstorefront.additionalWebSpringConfigs.<AddOnName>=classpath:/<AddOnName>/web/spring/<AddOnName>-web-spring.xml

Running the ant addoninstall Command

The following procedure describes how to run the ant addoninstall command.
  1. Before you run the ant addoninstall command:
    • Ensure that the addonsupport extension is listed in localextensions.xml file, as follows:
      ...
<extension name="addonsupport"/>
...
    • Also, ensure that the AddOn and storefront extension that you want to install are listed in localextensions.xmlfile.
    • If you have all your AddOns prepared as a single ZIP file, perform the following steps:
      1. Unzip all the AddOns that you wish to install into a subfolder of the <HYBRIS_BIN_DIR> folder. In the following example, the subfolder is called addoninstalldir.
      2. Add the following line to your localextensions.xml file:
        ...
<path autoload="true" dir="$\{HYBRIS_BIN_DIR\}/addoninstalldir"/>
...
    • Finally, make sure you have properly defined the project.properties.template file for each AddOn that you wish to install.
  2. Open the command prompt and navigate to the hybris/bin/platform directory.
  3. Run the addoninstall command. The command has the following format:
    ant addoninstall -Daddonnames="AddOnName1,AddOnName2" -DaddonStorefront.<storefrontTemplateName>="Storefront1,Storefront2"
  4. When addoninstall has finished running successfully, rebuild the SAP system by running ant clean all from thehybris/bin/platform directory.

Uninstalling an AddOn for a Specific Storefront

The addonuninstall tool can be used to remove an AddOn from the storefront.

The addonuninstall Tool

The following table lists the parameters of the addonuninstall tool:
ParameterNotes
addonnames
This parameter is mandatory. If more than one AddOn name is specified, the names must be separated by commas. If you do not include the addonnamesparameter when you run the addonuninstall command, you are asked to provide it.
addonStorefront.<storefrontTemplateName>
This parameter is used to indicate which storefronts you are uninstalling the AddOn from. If more than one storefront is specified, the storefront names must be separated by commas. The <storefrontTemplateName> variable indicates the storefront template that was used for storefront generation. By default, the two possible values are yacceleratorstorefront andyb2bacceleratorstorefront.
The ant addonuninstall command has the following format:
ant addonuninstall -Daddonnames="AddOnName1,AddOnName2" -DaddonStorefront.<storefrontTemplateName>="Storefront1,Storefront2"
The following is an example of the ant addonuninstall command, where two AddOns (NewAddOn1 and NewAddOn2) are uninstalled for B2CStorefront1 and B2CStorefront2, as well as for B2BStorefront1 and B2BStorefront2:
ant addonuninstall -Daddonnames="NewAddOn1,NewAddOn2" -DaddonStorefront.yacceleratorstorefront="B2CStorefront1,B2CStorefront2" -DaddonStorefront.yb2bacceleratorstorefront="B2BStorefront1,B2BStorefront2"

Running the ant addonuninstall Command

The following procedure describes how to run the ant addonuninstall command.
  1. Before you run the ant addonuninstall command, make sure the addonsupport extension is listed inlocalextensions.xml file, as follows:
    ...
<extension name="addonsupport"/>
...
  2. Open the command prompt and navigate to the hybris/bin/platform directory.
  3. Run the ant addonuninstall command. The command has the following format:
    ant addonuninstall -Daddonnames="AddOnName1,AddOnName2" -DaddonStorefront.<storefrontTemplateName>="Storefront1,Storefront2"
  4. When addonuninstall has finished running successfully, rebuild SAP Commerce by running ant clean all from thehybris/bin/platform directory.


Customizing the Storefront using an AddOn

You can customize a sample storefront and tailor it to your organization's requirements using AddOns.
Once you have set up the sample storefront, you can customize it to suit your needs using AddOns. The AddOns override the default configuration of the storefront so that it appears or behaves as desired.
Perform the steps below to customize the storefront:
  1. Create an AddOn. Refer to this page for the instructions on how to create a blank AddOn.
  2. Copy the storefront files that you wish to customize. The folder should have the same contents as the target storefront folder. Read more information here.
  3. Change any of the following files, if applicable. To do this, you may copy an existing template and customize it accordingly:
    • JSP Files
    • Impex Files
    • Tag Files
  4. Configure any of the following files, if applicable:
    • Spring
    • Controller
  5. Install the AddOn. Read the procedure here.
The following lists sample customizations on the Storefront:





Comments

Post a Comment

Popular Posts