Commerce Store Accelerator
Version 11.2
Developer Guide
Commerce Store Accelerator Developer Guide
Product version: 11.2
Release date: 10-22-15
Document identifier: CsaDevelopersGuide1603081515
Copyright © 1997, 2016 Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are
protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any
means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please
report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government,
the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the
hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable
Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or
documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended
for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures
to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are
trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services from third parties.
Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or
services, except as set forth in an applicable agreement between you and Oracle.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/
topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support: Oracle customers that have purchased support have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
if you are hearing impaired.
Commerce Store Accelerator Developer Guide iii
Table of Contents
1. Commerce Store Accelerator Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Architectural Styles and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Single-Page Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Representational State Transfer (REST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Model-View-ViewModel (MVVM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Component-based Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Client-side Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Store Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Logical View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Process View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Physical View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Commerce Store Accelerator Module Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Base Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Plugin Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3. Creating Commerce Store Accelerator Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Before Creating New Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Creating an Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Creating the Application Module’s Directory and File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuration for EAC Application Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Modifying the Build Configuration to Include the New Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Adding the EAC Application Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Running Gradle for the New Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Deploying the EAC Application and Initializing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Creating a Server Instance that Includes the New Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Starting the Oracle Commerce Server Instance and Running a Baseline Index . . . . . . . . . . . . . . . . . . . . . . . . 19
Testing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Adding an Out-of-the-Box Plugin to an Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Creating a New Plugin Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Creating the Plugin Module’s Directory and File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Configuring and Adding Code for the New Plugin Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Redeploying the Oracle Commerce Server Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Updating the EAC Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Restarting the Oracle Commerce Server Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Testing the New Plugin Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4. Using the Build System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Gradle Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Installing Third Party Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Setting Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Configuring your Node.js Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Installing the Node.js Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Running an Initial Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Running Gradle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using the Gradle Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Running Gradle Locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Choosing Where to Run Gradle From . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Relationship between Gradle Projects and Dynamo Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Root Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Specifying the Modules to Include in the Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
iv Commerce Store Accelerator Developer Guide
Defining Build Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Defining Common Configuration and Tasks for All Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Setting Global Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Common Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Defining Common Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Creating Sub-Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Creating Unit Tests for Your Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Building New Commerce Store Accelerator Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
IDE Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5. Client-side Routing in a Single-Page Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Client-side Routing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Detecting Requests for Specific URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Detecting Requests for Arbitrary URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Commerce Store Accelerator’s Out of the Box Use of changestate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6. Translating UI Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
UI String Translation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Configuring the i18next Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Loading the Resource File for the Current Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Replacing the {{ns}} Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Loading the Language-specific Resource File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Retrieving Translated Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Copying Source Translation Files during the Build Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Extending Translation Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7. Account Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Account Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Account Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Invoking the Account REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Account Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Required Application-specific Configuration for the Account Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Optional Application-specific Configuration for the Account Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8. Checkout Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Checkout Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Checkout Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Invoking the Checkout REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Checkout Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
AccessControlServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
EmailAccessController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
EmailRuleSetService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
CheckoutResources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
9. Preview Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Preview Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Preview Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Server Instance Configuration in CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
EAC Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Adding the Preview Plugin to the Application Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Modify the Application Module’s MANIFEST File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Add the DynamoHandler.properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Enabling Business Control Center Preview from within Visual Merchandising . . . . . . . . . . . . . . . . . . . . . . . . 65
Additional Configuration that Preview Depends Upon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
10. Promotions Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Promotions Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Promotions Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Invoking the Promotions REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Commerce Store Accelerator Developer Guide v
Promotions Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Required Application-specific Configuration for the Promotions Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Optional Application-specific Configuration for the Promotions Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
11. SEO Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
SEO Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Sitemap Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Handling SEO Requests in a Single-Page Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Canonical Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
SEO Tagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
SEO Plugin Required Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Configuring the Guided Search Sitemap Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Installing PhantomJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Configuring the Application Module and SEO Plugin Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Testing the SEO Plugin Using Adhoc Search Bot Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Populating the SEO Page Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12. SearchAndNavigation Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
SearchAndNavigation Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
SearchAndNavigation Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Invoking the SearchAndNavigation REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SearchAndNavigation Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Results List Optional Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Main Menu Optional Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Refinement Menu Optional Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Price Range Refinements Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Product Details Page Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
13. ShoppingCart Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Shopping Cart Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Shopping Cart Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Invoking the ShoppingCart REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ShoppingCart Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
14. Spotlights Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Spotlights Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Spotlights Plugin UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Spotlights Plugin Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Required Application-specific Configuration for the Spotlights Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Optional Application-specific Configuration for the Spotlights Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
15. Acronym Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
vi Commerce Store Accelerator Developer Guide
1 Commerce Store Accelerator Architecture Overview 1
1 Commerce Store Accelerator
Architecture Overview
Commerce Store Accelerator is a set of core reusable features, patterns and sample applications that simplifies
and reduces the lead time for constructing new Oracle Commerce web applications or introducing features into
an existing application. To accomplish this goal, Commerce Store Accelerator leverages modern technologies
and mature open source libraries, toolkits, and frameworks. This chapter provides an overview of the Commerce
Store Accelerator architecture and it includes the following sections:
Introduction (page 1)
Architectural Styles and Patterns (page 2)
Client-side Technology (page 3)
Store Overview (page 4)
Introduction
Commerce Store Accelerator includes the following modules:
• Base: This module contains all the core server and user interface code required to build an Oracle Commerce
store. All applications built using Commerce Store Accelerator use this module. It provides a JavaScript
framework, based on the Model, View ViewModel (MVVM) pattern, that allows you to create single page web
applications that use REST calls to interact with Oracle Commerce components and Experience Manager.
• Plugins: This module contains a number of sub-modules, for example, Checkout and
SearchAndNavigation. Each sub-module represents a set of features that you can choose to include in your
storefront application.
• Applications: This module contains the B2CStore sub-module, which is a sample storefront application
composed of the Base module and a number of the Plugins modules.
The Base module has dependencies on the third-party libraries and toolkits. A Plugins module may
have a dependency on the Base module or the third-party libraries. Because a sample application in the
Applications module combines the Base module with some number of Plugin modules, by extension, it
inherits the dependencies of those modules and also may have dependencies of its own.
You can use Commerce Store Accelerator in a variety of ways. If you need to build a storefront quickly, you can
use the existing code and re-skin the application by modifying its Bootstrap CSS theme. If you need to build an
2 1 Commerce Store Accelerator Architecture Overview
application that has a similar set of requirements to Commerce Store Accelerator, you can modify and extend it
as need be. For applications with requirements that do not overlap with Commerce Store Accelerator’s features
and page templates, you can still use the Base module to gain access to built-in functionality for initiating REST
calls as well as handling the Experience Manager request/response cycle.
Architectural Styles and Patterns
A Commerce Store Accelerator application is a client-server web application; the client application is a single-
page application and the server application is an extension of Oracle Commerce Platform.
Single-Page Application
Single-Page Application is the defining architectural style in Commerce Store Accelerator. Single-page
applications are native web applications; that is, they are applications that run natively in a web browser. With
single-page applications, the application is served directly to the browser for execution. This contrasts with
conventional web applications where the browser is served the result of an application run on the server. Single-
page applications are often (but not exclusively) client-server applications, connected to the server through
(RESTful) web service APIs.
Representational State Transfer (REST)
Representational State Transfer (REST) is based on the same architectural pattern as the Web. It is modeled
around a large number of resources that link amongst each other. Each resource can be globally identified by
its URI. With Oracle Commerce Platform, the resources that are being exposed by the REST web services are
server-side Nucleus components. It is important to keep in mind, however, that Oracle Commerce REST differs
from traditional REST as Oracle Commerce REST is not truly stateless and cannot be used to delete a Nucleus
component.
Client applications can leverage Oracle Commerce REST to interact with multiple types of Nucleus components
in a variety of ways. This includes invoking methods on standard Nucleus components, invoking form handlers
or performing create, read, update, and delete operations against the application’s repositories.
Model-View-ViewModel (MVVM)
The Model-View-ViewModel (MVVM) pattern is used to provide a clean separation of concerns between the user
interface controls and their underlying logic. The MVVM pattern consists of three core components: the model,
the view and the view model, each of which serves its own distinct and separate role, shown in the diagram
below.
1 Commerce Store Accelerator Architecture Overview 3
The model is a representation of the application’s domain model. Models hold information but do not handle
behavior or influence how the information appears to the end user which is the responsibility of the view.
The view controls the structure, layout and appearance of what the end user sees. The view is responsible for
representing the state of the view model. In the case of Commerce Store Accelerator, the view is constructed
from HTML documents that contain declarative bindings that link it to the view model.
The view model acts as the intermediary between the view and the model and is responsible for handling the
view logic. The view model retrieves data from the model and makes it available to the view through data
bindings. As part of this process, the view model may reformat the data in such a way that it is easier for the
view to work with it. The view model is also responsible for passing commands from the view to the model,
essentially acting as a middle man between the two.
Component-based Approach
Commerce Store Accelerator is an Oracle Commerce product and an extension of the Oracle Commerce
Platform. It therefore uses the same component-based development model as the rest of the Oracle Commerce
product suite. A Commerce Store Accelerator web application is assembled from Oracle Commerce components
that are linked through configuration files in Nucleus, resulting in a re-use friendly approach that defines,
implements, and composes independent components into a loosely coupled system.
Client-side Technology
The Commerce Store Accelerator client application is built using a number of third-party libraries, including:
• The Knockout JavaScript library is used to provide dependency tracking that allows the UI to automatically
update whenever the underlying data is changed and declarative bindings that connect parts of the UI to the
underlying data.
• JQuery is used for DOM manipulation. JQueryUI is used for widgets and effects.
• RequireJS is used for module dependency management.
• Bootstrap is used for its responsive grid system. This system provides a grid that manages content placement
on the rendered page and is modified according to the viewing device currently in use. Commerce Store
Accelerator implements a mobile first approach to responsive web design.
4 1 Commerce Store Accelerator Architecture Overview
• Crossroads.js is used for tracking changes to the URL and calling specific functions for specific URLs.
• i18next is an internationalization JavaScript library for translating web applications. Translations are stored in
a JSON hash compatible with WebTranslateIt JSON. Commerce Store Accelerator demonstrates a US Store that
supports English and Spanish languages and a Germany store that supports German and English languages.
Store Overview
This section describes the reference architecture for an Oracle Commerce application built with the Oracle
Commerce Store Accelerator. It uses the term Store to represent the highest level concept that encapsulates the
application implementation.
Logical View
The section below provides various perspectives on the logical view of a Commerce Store Accelerator
application.
Component View
Store can be viewed as a composition of two applications, store client and store server. Each has very different
architectures designed to support the functionality they must provide.
The client and server communicate through HTTP interface. Requests always come from the client and
responses from the server.
Note: See the Process View (page 5) section for more details on client-server interactions.
Module View
As is typical with Oracle Commerce applications, Store is a modular application. A naive view of this is presented
below.
1 Commerce Store Accelerator Architecture Overview 5
• The Store module represents the Oracle Commerce application, however, very little of the application is
implemented in Store. Its main purpose is to compose the features implemented in the plugins and serve as
the entry point to the application.
• The Plugins modules implement a set of Oracle Commerce features. Plugins are composed by Store to build
an Oracle Commerce application.
• The Base module is the foundation of a Store built using Commerce Store Accelerator and serves as an
extension of Oracle Core Commerce, defining all the shared interfaces and application-independent
functionality.
A merge package relationship exists between the Store, Base, and Plugins modules and is analogous to the
assembly of Oracle Commerce modules.
Process View
The Store client and server interact through an HTTP interface, where the client issues requests, and the server
responds. There are three types of requests, described below.
Request for Page Content to Experience Manager
As is typical with single-page applications, the Store client consumes page content as both HTML and JSON. As a
rule of thumb, the Content-Type is JSON for AJAX request and HTML for non-AJAX requests.
Content as HTML
A request for HTML content is typically the result of a non-AJAX HTTP request from the browser, which causes
the client to be loaded (or reloaded, as the case may be). As such, this is the mechanism by which the client
application is bootstrapped.
6 1 Commerce Store Accelerator Architecture Overview
1. The user enters the home page URL into the address bar.
2. The Store client sends a request for HTML to the home page URL.
3. The Store server sends the OK response and index.jsp is rendered as HTML.
Content as JSON
The default behavior of the single-page application Store client is to intercept hyperlink clicks and translate
those into AJAX requests. As such, link clicks generate a request for JSON content.
1. The user clicks on the home page link.
2. The Store client sends a request for JSON, typically using AJAX, to the home page URL.
3. The Store server sends the OK response and the home page content is rendered as JSON.
Request to an Oracle Commerce REST service
Oracle Commerce REST services provide an HTTP interface to Nucleus components. The Store CLIENT typically
invokes a REST service to perform some commerce business function, for example, adding an item to the cart.
1 Commerce Store Accelerator Architecture Overview 7
1. The user adds an item to the cart.
2. The Store client sends a request to the addItemToOrder endpoint.
3. The Store server sends an OK response and the updated order data to the Store client.
Request for Static Assets
Most Web pages load other static assets such as JavaScript, CSS, HTML, and images, which form part of the
complete page. Static asset requests are not handled by the Store server application but serviced directly by the
application/web server, or alternatively, a content delivery network. A typical interaction could be as follows.
1. The user enters the home page URL into the address bar.
2. The Store client sends a request for HTML to the home page URL.
3. The Store server sends an OK response and index.jsp is rendered as HTML.
4. The browser requests some JavaScript.
5. The browser requests some CSS.
6. The application server returns some JavaScript.
8 1 Commerce Store Accelerator Architecture Overview
7. The content deliver network returns some CSS.
Note: The number and nature of the requests is determined by the content of the HTML page.
Physical View
The illustration below depicts the Store as a distributed client-server architecture with an HTTP interface. In a
typical deployment, the Store client runtime is a browser and the Store server runtime is an application server.
Development View
CommerceAccelerator.Application.B2CStore is the reference implementation for a Commerce
Accelerator Store. The B2CStore module design is illustrated below.
1 Commerce Store Accelerator Architecture Overview 9
10 1 Commerce Store Accelerator Architecture Overview
In this illustration:
• The modules Base and Plugins.* are the Commerce Store Accelerator core modules and collectively
implement the Commerce Store Accelerator framework.
• Application.B2CStore is a realization of the Store module and as such composes features implemented in
the Plugins and serves as the entry point to the application.
• Base defines the “pluggable” interfaces for Plugins.*. Base is an extension of the DCS and REST modules.
• Application.B2CStore.Base defines the “pluggable” interfaces for
Application.B2CStore.Plugins.*. Application.B2CStore.Base is an extension of Base and can
override Base implementations or extend the Base interface.
• Plugins.* provide features by implementing interfaces from Base.
• Application.B2CStore.Plugins.* are extensions of the Plugins.* modules, and can override
Plugins.* implementations or realize new interfaces from Application.B2CStore.Base. Note that where no
corresponding B2CStore.Plugins.* extension exists the framework module is referenced directly.
• If a module uses an interface that is implemented in a different module there will be a dependency, for
example, Plugins.Checkout has dependencies on Plugins.Account and Plugins.Promotions. This can
be implemented as an explicit dependency defined in the META-INF, or an implicit dependency defined in
the startup script; an implicit dependency is recommended as it makes the architecture more flexible. Circular
dependencies are not supported.
2 Commerce Store Accelerator Module Overview 11
2 Commerce Store Accelerator
Module Overview
The chapter provides an overview of the Commerce Store Accelerator modules and how they interact with each
other. It includes the following sections:
Base Module (page 11)
Plugin Modules (page 12)
Base Module
The CommerceAccelerator.Base module is a required module for all of the Commerce Store Accelerator
plugin modules and it contains the framework of an application. When creating a new plugin module, you must
add the Base module to the new module’s MANIFEST.MF file.
The Base module itself is dependent on the REST, DCS, DCS.Endeca.Assembler and DCS.Endeca.Index
modules, as shown in the illustration below:
Server-side components that contain functionality useful to multiple plugins (or extensions of the Oracle
Commerce Platform implementations of these components) have been placed in the Base module. This
includes, for example, the CatalogTools, CatalogProperties, DimensionCache, RequestLocale
12 2 Commerce Store Accelerator Module Overview
components and more. Placing this functionality in a Base module reduces the amount of plugins that have
dependencies on each other while also ensuring that the Base module does not suffer from unnecessary bloat.
The Base module is where the client’s application object and prototype model objects (model,
domain-model, and view-model) are defined and also where the client itself is bootstrapped. The
client’s entry point (index.jsp and application.js) are defined in the Base module as well as the
RequiredModuleDependencies component, which gives you the ability to configure the modules that should
be included during application startup. Finally, you will also find all of the Commerce Store Accelerator custom
knockout bindings, filters, and internationalization objects that will aid you in the building of your commerce
site.
The Base module provides all of the XML templates and view models for the Experience Manager cartridges
related to page layout, for example, OneColumnPage, TwoColumnPage, PageHeader, PageFooter,
ContentSlotMain, ContentSlotSecondary, and so on. These cartridges are used by every plugin module in
Commerce Store Accelerator and provide you with the majority of layouts you may require when building your
Commerce Store Accelerator-based application.
Finally, general, site-wide configuration is found in the Base module, including Oracle Commerce Platform
configuration, Oracle Commerce configuration, Guided Search configuration, and any other configuration that is
required for generic commerce components that are required throughout the site.
Keep in mind that, while the Base module supplies all of the above functionality and configures the foundation
of a commerce site, you still have the option to extend the Base module for your own application, overriding the
out-of-the-box configuration and tailoring the site to your requirements.
Plugin Modules
Commerce Store Accelerator leverages the concept of plugin modules. Each Commerce Store Accelerator
plugin module is dependent on the CommerceAcclerator.Base module and offers its own discrete piece of
functionality that forms the foundation of a part of a commerce store, for example, Account, ShoppingCart,
Checkout, and so on. All plugins modules are found in <ATG11dir>/CommerceAcclerator/Plugins.
With the exception of the framework code found in CommerceAccelerator.Base, the majority of the plugin
modules contain all of the client and server code, as well as any configuration or Experience Manager cartridge
templates, that are required in order to implement the piece of commerce functionality that the plugin
represents. Wherever possible, plugin modules have been encapsulated so they do not rely on each other. If
a dependency between two plugin modules was unavoidable, a clear API has been provided. This approach
allows you to replace the functionality in a plugin module with a third-party or custom-built alternative if your
application requires it.
The following table and diagram show the inter-module dependencies at both compile time and run time.
Plugin Module Run-time Dependencies Compile-time Dependencies
Account Base None
Checkout Base, Account, Promotions None
Preview Base None
2 Commerce Store Accelerator Module Overview 13
Plugin Module Run-time Dependencies Compile-time Dependencies
Promotions Base None
SearchAndNavigation Base ShoppingCart
SEO Base None
ShoppingCart Base None
Spotlights Base None
14 2 Commerce Store Accelerator Module Overview
3 Creating Commerce Store Accelerator Modules 15
3 Creating Commerce Store
Accelerator Modules
This chapter describes how to create new application and plugin modules based on the Commerce Store
Accelerator code base. It also describes how to add an out-of-the-box plugin to an existing application. It
includes the following sections:
Before Creating New Modules (page 15)
Creating an Application Module (page 15)
Adding an Out-of-the-Box Plugin to an Application Module (page 21)
Creating a New Plugin Module (page 21)
Before Creating New Modules
Creating new modules makes use of the Commerce Store Accelerator build system. Before you create new
modules, you must ensure your environment is prepared properly for the build system. To do this, follow the
instructions in the Software Requirements (page 28) section of the Using the Build System (page 27)
chapter.
Creating an Application Module
To create an application module, you must:
• Create the module’s directory and file structure, using the templates provided in CommerceAccelerator/
module_templates.
• Perform some manual configuration to allow communication between Oracle Commerce server instances and
the EAC applications that support them.
• Modify the build configuration to include the new application module.
• Add the EAC Application source files that will be used by the build process.
• Run the Gradle build process for the new application module.
16 3 Creating Commerce Store Accelerator Modules
• Deploy the EAC applications that will support the new application module and initialize services for them.
• Create an Oracle Commerce server instance that includes the new application module.
• Start the Oracle Commerce server instance and run a baseline index.
• Test the application by creating some test content, publishing and promoting it, then opening the application
in a browser.
Creating the Application Module’s Directory and File Structure
To create a new application module’s directory and file structure:
1. Create a directory for your application module in CommerceAccelerator/Applications.
2. Copy the contents of the CommerceAccelerator/module_templates/Application directory to your
CommerceAccelerator/Applications/application-name directory.
3. In the following files, replace <%= appName %> with your application module’s name:
• application-name\build.gradle
• application-name\gradle.properties
• application-name\Base\build.gradle
• application-name\Base\src\main\web-app\bower.json
• application-name\META-INF\MANIFEST.MF
• application-name\Plugins\build.gradle
• application-name\src\main\web-app\bower.json
• application-name\src\main\web-app\main.js
• application-name\src\test\web-app\main.spec.js
4. In the following files, replace <%= contextRoot %> with your application module’s context root:
• application-name\src\main\j2ee-apps\META-INF\application.xml
• application-name\src\main\web-app\META-INF\MANIFEST.MF
• application-name\src\main\web-app\WEB-INF\web.xml
Configuration for EAC Application Communication
You must do some manual editing to configure communication between any server instances you create and
the EAC applications that support them. In the CommerceAccelerator/Applications/application-name/
src/main/config directory, make the following edits:
1. In the /atg/endeca/ApplicationConfiguration.properties file, uncomment and edit the
baseApplicationName , locales, and applicationKeyToMdexHostAndPort properties to reflect your
application’s requirements, for example:
baseApplicationName=NewStore
locales=en_US
3 Creating Commerce Store Accelerator Modules 17
applicationKeyToMdexHostAndPort=default=localhost:15000
For a multiple EAC application environment, the applicationKeyToMdexHostAndPort property would
look similar to the following:
applicationKeyToMdexHostAndPort=en=localhost:15000,de=localhost:16000,es=localhost:17000
And the locales property would look similar to this:
locales=\
en_US,\
de_DE,\
es_US
2. In the /atg/endeca/assembler/AssemblerApplicationConfiguration.properties file, edit the
assemblerContentBaseDirectory property to reference the location where your Assembler application
export archive files are kept. For example:
assemblerContentBaseDirectory=C:/Endeca/Apps/application_export_archive
IMPORTANT: Use forward slashes for this path, even on Windows.
3. If your environment has multiple EAC applications, then the default configuration of the /atg/endeca/
assembler/admin/EndecaAdministrationService component must be changed as follows:
• Add the class declaration $class=atg.endeca.assembler.MultiAppAdministrationService
• Comment out or remove the storeFactory=/atg/endeca/assembler/cartridge/manager/
DefaultFileStoreFactory property. Optionally, add custom store factories if your application requires
them.
Note: Using the MultiAppAdministrationService component means that storeFactories are
automatically generated at run-time and do not need to be manually configured unless your application
requires you to explicitly create them.
4. In the /atg/multisite/DefaultSiteRuleFilter.properties file, uncomment and configure the
defaultSiteId property to specify the site ID for your default site as defined in Site Administration.
Note: For more information on the ApplicationConfiguration , AssemblerApplicationConfiguration,
and EndecaAdministrationService components, see the Platform-Guided Search Integration Guide.
Modifying the Build Configuration to Include the New Application Module
The CommerceAccelerator/settings.gradle file specifies the Dynamo modules that are included in the
build. You must add entries for the new application module and its sub-modules to the settings.gradle file,
for example:
"Applications:NewStore","Applications:NewStore:Base","Applications:NewStore:Plugins"
Take care that each line in the settings.gradle file ends with a comma except for the final line.
Also, EAC applications that should have deployment templates created for them as part of the gradle
build must be configured in the eacApplications property of the CommerceAccelerator/
Applications/application-name/gradle.properties file, for example:
18 3 Creating Commerce Store Accelerator Modules
eacApplications=NewStoreen
Adding the EAC Application Source Files
Create directories for any new EAC applications that will support the new Commerce Store Accelerator
application module under CommerceAccelerator/Applications/application-name/src/main/eac-
templates, for example, CommerceAccelerator/Applications/application-name/src/main/eac-
templates/EAC-application-name. The eac-templates location functions as a staging area for the gradle
build.
Include any content you want your new EAC applications to contain. At a minimum, you must have one EAC
application and it must:
• Be associated with the site specified in the defaultSiteId property of the /atg/multisite/
DefaultSiteRuleFilter component.
• Include a page to represent /home.
• Contain content for the /home page to display. For the examples in this chapter, we will assume the EAC
application has content in the form of Web/Home Pages/Default Home Page.
Running Gradle for the New Application Module
You must run Gradle to include your new module in the build and create the deployment template for your EAC
application.
To run the build:
1. In a command prompt or shell window, navigate to the CommerceAccelerator directory.
2. Enter the following command if you have Gradle installed locally:
gradle
Note: If you are using the Gradle wrapper, use gradlew instead.
After the gradle command runs, a new directory, CommerceAccelerator/Applications/application-
name/src/main/deploy/EAC-application-name, will exist for each EAC application you created. Each EAC-
application-name directory will contain all of the files required for EAC application deployment, including the
deploy.xml script.
Deploying the EAC Application and Initializing Services
After the gradle build creates the deploy.xml template for your EAC applications, you can deploy them to
Experience Manager and initialize services. You can deploy the EAC applications through CIM or through a
script. Before deploying, make sure the EAC application deployment path exists; for example, if you want to
deploy your EAC applications to C:\Endeca\Apps, make sure that directory exists before deploying. For details
on deploying an EAC application either through CIM or through a script, see the Commerce Store Accelerator
Installation and Configuration Guide.
After deploying your EAC applications, you must initialize them.
To initialize the EAC application:
3 Creating Commerce Store Accelerator Modules 19
1. In a UNIX shell or command prompt, change directories to your EAC application’s /control directory, for
example, /usr/local/endeca/Apps/EAC-application-name/control or C:\Endeca\Apps\EAC-
application-name\control.
2. Execute the initialize_services.sh script. For example, on UNIX, enter:
./initialize_services.sh
On Windows, enter:
initialize_services.bat
Creating a Server Instance that Includes the New Application Module
Note: This section assumes you have created and populated the database that will support your Oracle
Commerce server instance.
You can use CIM to create an Oracle Commerce server instance that will include your new application module.
At a minimum, you must create a production server instance that includes the following Oracle Commerce
products:
• Oracle Commerce Site Admin
• Oracle Commerce Platform-Guided Search Integration
• Oracle Commerce Store Accelerator
Additonally, you must do the following when configuring the server instance:
• Configure OPSS security settings, including configuring the Workbench login.
• Do not include the B2Cstorefront.
• Add the new application module to the Oracle Commerce server instance. Its naming syntax should
be CommerceAccelerator.Applications.application-name. Place it in the module list after the
CommerceAccelerator.Base module.
You may choose to include other products, for example, REST services, but the three products listed above are
the only ones required to create a new application module. The other choices you make in CIM as you create
your server instance, for example, whether to use a switching or non-switching database, are application-specific
and should not impact the instructions presented in this chapter.
Note: For definitions of many of the prompts you may encounter as you configure the Oracle Commerce
server instance, refer to the Commerce Store Accelerator Installation and Configuration Guide. If you are on a
Windows environment, be sure to use the correct slash style (forward slash versus back slash) as you answer the
prompts. Slash styles are indicated in the prompt definitions in the Commerce Store Accelerator Installation and
Configuration Guide.
Starting the Oracle Commerce Server Instance and Running a Baseline Index
At this point, you must start the Oracle Commerce server instance. For detailed instructions on starting Oracle
Commerce server instances, you can refer to the Commerce Store Accelerator Installation and Configuration Guide.
After starting the server instance, you must run a baseline index.
To run a baseline index:
20 3 Creating Commerce Store Accelerator Modules
1. In a browser, go to the Dynamo Server Admin on your server instance:
http://<server-host>:<server-HTTP-port>/dyn/admin
2. Click the Component Browser link, and then use the subsequent links to navigate to the /atg/commerce/
endeca/index/ProductCatalogSimpleIndexingAdmin component.
3. Click the Baseline Index button to start a baseline index.
4. Ensure that the Auto Refresh option is selected so that the status information is refreshed.
5. When the Status for all phases is COMPLETE (Succeeded), proceed to the next section to test your new
application.
Testing the Application
If your application does not have any visible content in it yet, you can test it by adding a RichTextMain
cartridge with some sample text to the MainContent area of the home page in Experience Manager. After
adding the content, you must publish and promote it, and then you can open the application’s home page in a
browser and confirm it is working correctly. These instructions assume you have the content for your home page
in Web/Home Pages/Default Home Page in Experience Manager.
To add test content in a RichTextMain cartridge:
1. In a browser, navigate to http://<Workbench_host>:8006/ifcr.
2. Enter your Workbench username and password (If you followed the instructions in the Commerce Store
Accelerator Installation and Configuration Guide, this is admin for the username and Admin123 for the
password) and click Log In.
3. From the Administrative Tools menu, select your EAC application, then click Experience Manager.
4. Under Rules, expand Web, expand Home Pages, then click Default Home Page.
5. In the Editor tab, click mainContent.
6. Click the Add button, select RichTextMain and click OK.
7. Click the Enter text button, enter some sample text and click OK.
8. Click Save in the upper-right corner.
9. Click the Untitled work menu and click Publish, then click Publish again.
To promote the test content:
1. Open a UNIX shell or command prompt on the server that is running Guided Search with Experience
Manager.
2. Change directories to the EAC application’s control directory, for example:
cd /usr/local/endeca/Apps/EAC-application-name/control
or
cd C:\Endeca\Apps\EAC-application-name\control
3. Enter one of the following commands.
UNIX:
3 Creating Commerce Store Accelerator Modules 21
./promote_content.sh
Windows:
promote_content.bat
To view the promoted content and verify that your new application module is working as expected, open a
browser and navigate to your applications home page, for example:
http://server-name:http-port/context-root/home
Adding an Out-of-the-Box Plugin to an Application
Module
Commerce Store Accelerator ships with a number of plugin modules, for example, Checkout, Promotions, and
SearchAndNavigation. The process for adding an out-of-the-box plugin module to an application requires of
a subset of the steps you follow for creating a new plugin module and adding it to an application. To add an out-
of-the-box plugin module, you can use the procedure in the Creating a New Plugin Module (page 21) section
with some modifications. Specifically, skip any steps marked [New Plugins Only] or marked to indicate that the
step is not appropriate for the plugin you want to add.
IMPORTANT: The Preview and SEO plugins do not follow the standard procedure for adding a plugin. Refer to
the Preview Plugin (page 61) and SEO Plugin (page 69) chapters for detailed information on incorporating
those two plugins into a new application module. Also, for some of the other out-of-the-box plugins, additional
application-specific configuration is required in order for the plugins to work properly. See the individual plugin
chapters for more details.
Creating a New Plugin Module
Follow the procedures below to create a plugin module and add it to an application module.
Note: If you are using these procedures to add an out-of-the-box plugin to an application, skip the steps marked
[New Plugins Only].
Creating the Plugin Module’s Directory and File Structure
[New Plugins Only] To create the new plugin module’s directory and file structure:
1. Create a directory for your plugin module in CommerceAccelerator/Plugins.
2. Copy the contents of the CommerceAccelerator/module_templates/Plugin directory to your
CommerceAccelerator/Plugins/plugin-name directory.
3. In the following files, replace <%= pluginName %> with your plugin module’s name:
• plugin-name\build.gradle
22 3 Creating Commerce Store Accelerator Modules
• plugin-name\META-INF\MANIFEST.MF
• plugin-name\src\main\web-app\bower.json
Note: These file modifications are also detailed in the CommerceAccelerator/module_templates/
template_placeholders_to_be_replaced.txt file.
Configuring and Adding Code for the New Plugin Module
IMPORTANT: As you edit the arrays in the following files, be careful that each line has a comma at the end
except for the last line in the array.
To configure the new plugin module:
1. [New Plugin Only] Add the following string to the dependencies property in
CommerceAccelerator/Plugins/plugin-name/src/main/config/atg/dynamo/service/
RequiredModuleDependencies.properties. Setting this property includes the new plugin module’s
main file in the required packages during start up. Be sure to include the single quotes.
dependencies+='bower_components/CSA.Plugins.plugin-name/main'
2. [New Plugins Only] Create a CommerceAccelerator/Plugins/plugin-name/src/main/deploy directory
and populate it with the cartridge templates for the plugin. The directory structure you use for the templates
is important because the build expects all files related to the plugin’s cartridges to be in specific locations.
Also, the EAC application deployment process expects to find an EAC application’s deployment templates in
specific locations. The required directory structure is shown in the following table:
Directory Description
/cartridge-name/import/templates/
_.json
The same _.json file is used for all cartridges and it
contains the following code:
{
"ecr:type":"template"
}
/cartridge-name/import/templates/
thumbnail.png
Used by Experience Manager as the image displayed
when viewing the list of available cartridges.
/cartridge-name/import/templates/
template.xml
The cartridge’s template file.
/cartridge-name/import/templates/
locales
Resource files that contain any required translations for
the internationalization of the cartridge.
3. [New Plugins Only] Populate the CommerceAccelerator/Plugins/plugin-name/src/main/web-app
directory with the JavaScript modules (.js files) and HTML renderers (.html files) that support your plugin
module’s cartridges.
4. [New Plugins Only] Edit the file CommerceAccelerator/Plugins/plugin-name/src/main/web-app/
main.js file to add the cartridges’ JavaScript modules to the namespace mappings, for example:
// Define local configuration
3 Creating Commerce Store Accelerator Modules 23
require.config({
paths: {
// Canonical namespaces mappings [package local modules] (aka
// implementation mappings) -->
'CSA.Plugins.plugin-name/js-module-name':
'bower_components/CSA.Plugins.plugin-name/js-module-name'
},
map: {
'*': {
// Public to Canonical namespace mappings (aka interface to
// implementation mappings) -->
'js-module-name': 'CSA.Plugins.plugin-name/js-module-name'
}
}
});
5. To add the plugin module to an existing application module, edit the application module’s
gradle.properties file to specify the plugin module in the includedPlugins property. For example,
in the CommerceAccelerator/Applications/application-name/gradle.properties file, edit the
includedPlugins property as follows:
includedPlugins=CommerceAccelerator.Plugins.plugin-name
This ensures that the plugin module is built when gradle is executed.
6. [Note: Skip this step if you are adding the Preview plugin module to an application.] To ensure
that the plugin module is included in the optimized build, update the CommerceAccelerator/
Applications/application-name/Gruntfile.js to include the new plugin module’s main.js in the
mainConfigFile array:
mainConfigFile: [
'src/main/web-app/bower_components/CSA.Base/main.js',
'src/main/web-app/bower_components/CSA.Plugins.plugin-name/main.js'
]
7. [Note: Skip this step if you are adding the Preview plugin module to an application.] To ensure that
the JavaScript modules that support the plugin module are included in the optimized build, update the
CommerceAccelerator/Applications/application-name/Gruntfile.js to add a line for the plugin’s
main module and also for each of the plugin’s cartridge modules inside the include array:
include: [
.
.
.
'bower_components/CSA.Plugins.plugin-name/main',
'CSA.Plugins.plugin-name/js-module-1-name',
'CSA.Plugins.plugin-name/js-module-2-name',
'CSA.Plugins.plugin-name/js-module-N-name'
]
Note: The optimized build takes all of the individual files listed in the include array and merges them into
a single, large JavaScript file. This allows the browser to load the site using a single request, as opposed to
hundreds of requests for the individual JavaScript modules.
8. To make the plugin module start up with the rest of the application module, update the
CommerceAccelerator/Applications/application-name/META-INF/MANIFEST.mf file to add
24 3 Creating Commerce Store Accelerator Modules
CommerceAccelerator.Applications.application-name.Plugins to the ATG-Required property.
If the line exceeds a length of 72 characters when adding this module name to the ATG-Required property,
ensure that all text after the 72nd character is wrapped onto the next line as shown in the example below:
Note: If you are adding an out-of-the-box plugin module to an existing application, this step may already
have been done for other plugins that were included in the application module.
9. Update the CommerceAccelerator/Applications/application-name/src/main/web-app/
bower.json file to add the CSA.Plugins.plugin-name reference as shown below:
{
"name": "CSA.Applications.application-name",
"version": "1.0.0",
"ignore": [
"*"
],
"dependencies": {
"CSA.Applications.application-name.Base":
"../../../Base/src/main/web-app",
"CSA.Base": "../../../../../Base/src/main/web-app",
"CSA.Plugins.plugin-name":
"../../../../../Plugins/plugin-name/src/main/
web-app"
},
"devDependencies": {
"es5-shim": "3.4.0",
"jasmine": "1.3.1"
}
}
The bower.json files are used to manage the package dependencies for the client-side application. Every
Commerce Store Accelerator module that contains client-side code contains one of these files. When the
build is run, the bower task creates a bower_components directory in the root directory of the module. The
build then uses the bower.json file to populate this directory with the require dependencies.
The dependencies object in the bower.json file contains the required dependencies. To the left of each
ellipsis is the name of a directory to be created in the bower_components directory while on the right is the
path to use when copying the dependency.
10.[New Plugins Only] To add the plugin module to the build, update the CommerceAccelerator/
settings.gradle file to add a reference to "Plugins:plugin-name" at the end of the list. Take care that
each line in the settings.gradle file ends with a comma except for the final line.
11.If the Oracle Commerce server instance that will include the new plugin is still running, stop it.
12.In a command prompt or UNIX shell, navigate to the CommerceAccelerator directory and run gradle.
Redeploying the Oracle Commerce Server Instance
You must re-deploy the server instance after doing the manual configuration and running the build. You can use
CIM to re-deploy by selecting the [4] Application Assembly & Deployment option in the CIM MAIN MENU and
running through its tasks.
3 Creating Commerce Store Accelerator Modules 25
Updating the EAC Application
To add the cartridges defined in the new plugin to the EAC application, follow the instructions below.
1. Copy the cartridge template directories associated with the new plugin from the CommerceAccelerator
\Applications\application-name\src\main\deploy\EAC-application-name\import\templates
folder to the Endeca\Apps\EAC-application-name\config\import\templates folder.
2. In a command prompt or UNIX shell, navigate to the Endeca\Apps\EAC-application-name\control
directory.
3. Run the following command:
runcommand.bat IFCR importApplication ..\config\import
Restarting the Oracle Commerce Server Instance
At this point, you must restart the Oracle Commerce server instance. See Starting the Oracle Commerce Server
Instance and Running a Baseline Index (page 19) for detailed instructions.
Testing the New Plugin Module
To test the new plugin module, add a cartridge from your new plugin to a page in Experience Manager. After
adding the cartridge, save, publish and promote the new content, and then open the application in a browser
and confirm the content is appearing as expected.
26 3 Creating Commerce Store Accelerator Modules
4 Using the Build System 27
4 Using the Build System
This chapter describes how to use the Commerce Store Accelerator build system to rebuild Commerce Store
Accelerator after its modules have been modified or new modules have been added. It includes the following
sections:
Gradle Introduction (page 27)
Software Requirements (page 28)
Running Gradle (page 29)
Relationship between Gradle Projects and Dynamo Modules (page 30)
Root Project Configuration (page 30)
Specifying the Modules to Include in the Build (page 30)
Defining Build Properties (page 31)
Defining Common Configuration and Tasks for All Projects (page 32)
Creating Sub-Modules (page 39)
Creating Unit Tests for Your Modules (page 39)
Building New Commerce Store Accelerator Modules (page 40)
IDE Integration (page 40)
Gradle Introduction
Commerce Store Accelerator includes a set of Gradle build scripts that allow you to quickly and easily rebuild
Commerce Store Accelerator after modules have been added, removed, or modified. Gradle is a build system
that expands upon the concepts of Ant and Maven and uses a Groovy-based dynamic scripting language
instead of XML to declare the build configuration. Gradle supports incremental builds by intelligently
determining which parts of the build tree are up to date, so that any task dependent upon those parts will not
need to be re-executed.
Note: This chapter assumes you are familiar with the Gradle build system. To learn more about Gradle, refer to its
web site and documentation at http://www.gradle.org/.
28 4 Using the Build System
Software Requirements
The Commerce Store Accelerator build relies on several packages and environment variables. Be sure your
machine meets the requirements described below before attempting to build.
Installing Third Party Programs
Install the following third party packages, being careful to use the versions provided:
• Gradle, version 1.7
• Node.js, version 0.10.29 (including the npm node package manager)
• GIT (1.8.3 or a later stable version)
Setting Environment Variables
If you are running your environment behind a proxy server, set the following environment variables:
• HTTP_PROXY=http://proxy_host:proxy-port
• HTTPS_PROXY=http://proxy_host:proxy-port
Set the following environment variables for Gradle:
• GRADLE_HOME=gradle-directory, (for example, C:\gradle-1.7-all\gradle-1.7
• If your environment uses proxy servers, set GRADLE_OPTS= -Dhttp.proxyHost=proxy-host -
Dhttp.proxyPort=proxy-port
Add the following to the PATH environment variable:
• gradle-home\bin, for example, C:\gradle-1.7-all\gradle-1.7\bin
• git-home\bin, for example, C:\Git\bin
• git-home\cmd, for example, C:\Git\cmd
Configuring your Node.js Proxy
In a command prompt or UNIX shell, enter the following commands to configure the proxy servers that Node.js
uses.
npm config set proxy http://proxy-host:proxy-portnpm config set https-proxy http://proxy-host:proxy-port
Installing the Node.js Dependencies
To install the Node.js dependencies, in a command prompt or UNIX shell, enter the following command:
npm install -g bower grunt-cli
4 Using the Build System 29
Running an Initial Build
To make sure all the Node and Bower dependencies are downloaded and your environement is properly set up,
run an initial build.
To run an initial build:
1. In a command prompt or UNIX shell, change directories to <ATG11dir>/CommerceAccelerator.
2. Run the following command:
gradle
Note: If you are using the Gradle wrapper, use gradlew instead.
Running Gradle
You have two options for running Gradle. You can install it locally and then run it from the local installation.
Alternatively, Commerce Store Accelerator is packaged with several wrapper resources that allow you to run a
Gradle build without a local installation.
Using the Gradle Wrapper
To use the Gradle wrapper, you use the gradlew task command, for example:
gradlew all
Note: See https://gradle.org/docs/current/userguide/gradle_wrapper.html for more information on the Gradle
wrapper.
Running Gradle Locally
To run Gradle from your local install, use the gradle task command, for example:
gradle all
Choosing Where to Run Gradle From
To build all of the Commerce Store Accelerator modules, change to the <ATG11dir>/CommerceAccelerator
directory and run Gradle from that directory. To build an individual module, along with any modules the
individual module depends on, run Gradle from the directory where the module’s build.gradle file is
located. For example, to build the B2CStore directory and its dependencies, run Gradle from the <ATG11dir>/
CommerceAccelerator/Applications/B2CStore directory. If you make changes to a file that a client
application depends on (for example, an HTML or JavaScript file), you must run the build from the <ATG11dir>/
CommerceAccelerator directory or the affected application module’s directory to ensure that the edited files
are pulled into the store.war.
30 4 Using the Build System
Note that, out of the box, all of the Commerce Store Accelerator modules are configured to run the default all
task if you do not specify a task on the command line. In other words, running gradle is equivalent to running
gradle all. For more details on this default configuration, see Creating Sub-Modules (page 39).
Relationship between Gradle Projects and Dynamo
Modules
Each Dynamo module in Commerce Store Accelerator corresponds to a Gradle project and has its own
build script. In other words, the CommerceAccelerator module has its own build script, as does each
of the CommerceAccelerator sub-modules, and those scripts manage how each module is built. The
CommerceAccelerator build script, located in <ATG11dir>/CommerceAccelerator/build.gradle,
functions as the root build script for Commerce Store Accelerator. The build.gradle scripts located in the sub-
modules extend the root build.gradle script.
Root Project Configuration
Because it is the root project, the CommerceAccelerator module includes several files that manage the overall
build process:
• settings.gradle specifies the modules that should be included in the build.
• gradle.properties defines global properties, such as Dynamo home, that are used by the build process.
• build.gradle defines configuration and tasks that are common across all build projects. To distinguish it
from the build.gradle scripts that can reside in sub-modules, this file is called the root build.gradle file
throughout this documentation.
These files are described in more detail in the sections below.
Specifying the Modules to Include in the Build
The settings.gradle file specifies the Dynamo modules (which, as described in the Relationship between
Gradle Projects and Dynamo Modules (page 30) section, correspond to Gradle projects) that should be
included in the build. Out of the box, the modules to include are specified as follows:
include "Base", "Plugins", "Plugins:SearchAndNavigation", "Plugins:Spotlights", "Plugins:ShoppingCart", "Plugins:SEO", "Plugins:Account",
4 Using the Build System 31
"Plugins:Preview", "Plugins:Checkout", "Plugins:Promotions", "Applications", "Applications:B2CStore", "Applications:B2CStore:Base", "Applications:B2CStore:Plugins", "Applications:B2CStore:Plugins:SearchAndNavigation", "Applications:B2CStore:Plugins:ShoppingCart", "Applications:B2CStore:Plugins:Account", "Applications:B2CStore:Plugins:Checkout", "Applications:B2CStore:Plugins:Spotlights", "Applications:B2CStore:NoPublishing", "Applications:B2CStore:Versioned", "Applications:B2CStore:CIMExtension"
Defining Build Properties
Each module can have a gradle.properties file. This file defines build properties, for example, dynamoHome,
that are used by the build process.
Note that the gradle.properties file cannot use variables in build property values. In other words, the file
must use:
dynamoHome=C:/work/ATG/platform/Dynamo/home
Instead of
dynamoHome=${env.dynamoHome}/..
In order to use variables in build property values, the properties must be defined in a build.gradle file instead
of the gradle.properties file. This can be either the root build.gradle file, if the properties are used by
multiple Gradle projects, or the build.gradle file of the specific project that requires the properties. You
define the properties using Gradle’s ExtraPropertiesExtension API, which uses a syntax that looks like this:
project.ext.myProperty = propertyValue1;project.ext.myOtherProperty = propertyValue2;
Alternatively, you can set multiple properties using a Gradle configuration closure:
project.ext { myProperty = "propertyValue1" myOtherProperty = "propertyValue2" }
The combination of the settings in the gradle.properties file and the project.ext.<property>
definitions acts as a key/value map that provides access to the build properties to other build files.
32 4 Using the Build System
IMPORTANT: The example above sets dynamoHome. Note that, when setting dynamoHome in the
gradle.properties file, you must use forward slashes, even if you are on Windows.
Defining Common Configuration and Tasks for All Projects
The root build.gradle script in the CommerceAccelerator module contains all of the common build logic
and configuration for the CommerceAccelerator module and its sub-modules.
Setting Global Configuration
The root build.gradle script includes several global configuration closures. These closures are executed once
when you run your build (as opposed to the tasks in the allprojects closure, which get executed for each
project).
excludeNonDevBuildTasks
The excludeNonDevBuild configuration closure retrieves the Boolean value of the devBuild property,
which is set either in the gradle.properties file or on the command line when Gradle is run. If the value is
true, the build is run as normal and all tasks and task dependencies are executed. If the value is false, several
development-related tasks are excluded from the build process. Out of the box, the tasks to exclude are test
(unit tests) and jshint (JavaScript formatting and syntax checking).
setDynamoClasspath
The setDynamoClasspath configuration closure builds the Dynamo classpath using a custom ant task
(atg.applauncher.taskdef.DynamoClasspathTask). The requiredPlatformModules property of the
root gradle.properties file defines the Oracle Commerce Platform modules that are included the Dynamo
classpath. Out of the box, this property looks like this:
requiredPlatformModules=\ DCS.ADC;DAF.Endeca.Assembler;DAF.Endeca.Index;DPS-UI;SiteAdmin.Versioned
setDynamoHome
The setDynamoHome configuration closure sets the dynamoHome value to be used by the build scripts. The
dynamoHome value is obtained from one of three locations:
1. setDyanmoHome first tries to retrieve the value for dynamoHome from the command line arguments used
when running Gradle. To pass a dynamoHome value on the command line, use:
-- PdynamoHome=<path_to_dynamoHome>
or
--project-prop dynamoHome=<path_to_dynamoHome>
2. If dynamoHome has not been defined on the command line, the value set for dynamoHome in the root
gradle.properties file is used.
IMPORTANT: If you choose to set dynamoHome in the gradle.properties file, you must use forward
slashes, even if you are on Windows.
4 Using the Build System 33
3. If the dynamoHome value has not been defined in either of the above locations, the value of the DYNAMO_HOME
system environment variable is used.
If the dynamoHome value cannot be determined from any of the above locations, the build fails.
setProxy
The setProxy configuration closure retrieves the httpProxy and httpsProxy property values from the
gradle.properties file and assigns them to a global proxySettings variable. This global variable can then
be used in Exec tasks (tasks that run executables on the command line). For example, the bowerInstall task
must retrieve packages from across the network, so it requires the proxySettings variable. The syntax for
specifying an Exec task that uses the proxySettings variable is:
task('myExecTask', type: Exec) { environment proxySettings; commandLine cmd|cmd.bat, "cmdArg"}
Common Project Configuration
The allprojects closure in the root build.gradle script defines configuration settings and tasks that are
executed for each Commerce Store Accelerator module.
Plugin Configuration
The allprojects closure applies three Gradle plugins that provide access to tasks that the Commerce Store
Accelerator build process uses:
apply plugin: 'java'apply plugin: 'eclipse'apply plugin: com.eriwen.gradle.js.JsPlugin
The java plugin includes tasks that compile classes, create JAR files, run unit tests, and so on. For more
information on this plugin, see http://www.gradle.org/docs/current/userguide/java_plugin.html.
The eclipse plugin generates files that are used by the Eclipse IDE. These files are necessary in order to build
a Gradle project from within Eclipse. For more information on this plugin, see http://www.gradle.org/docs/
current/userguide/eclipse_plugin.html.
The com.eriwen.gradle.js.JsPlugin plugin is a third-party plugin that includes useful JavaScript tasks
such as gradle jshint, a task that validates JavaScript code style and formatting. For more information on this
plugin, see https://github.com/eriwen/gradle-js-plugin.
Repository Configuration
The repositories script block of the allprojects task defines the public mavenCentral repository as the
location from which third-party libraries that the build tasks depend on, such as junit, should be retrieved
from:
repositories { mavenCentral() }
34 4 Using the Build System
Java Source Code and Resource File Locations
Any Java source code that is required to build a module should be placed in that module’s /src/main/java
directory. The following configuration in the allprojects task tells the Gradle build system to look in each
module’s /src/main/java directory for Java source code:
sourceSets.main.java.srcDirs = ["src/main/java"];
Likewise, the Gradle build system needs to know where to find resource files. Because Oracle Commerce
resource files can be included in the Java source code, the Gradle build system needs to look in both the
<module>/src/main/java directories as well as in Gradle’s default location of <module>/src/main/
resources for resource files. The following configuration in the allprojects task tells the Gradle build system
to look in both locations for resource files:
sourceSets.main.resources.srcDirs = ["src/main/java", "src/main/resources"];
Dependencies Configuration
The specific JAR files, classpaths, and arguments used during the execution of various build process tasks are
defined in the dependencies script block of the allprojects task:
dependencies {
//------------------------- /** * Unit test dependencies. */ testCompile( [group: "junit", name: "junit", version: "4.11"], [group: "hsqldb", name: "hsqldb", version: "1.8.0.7"], [group: "org.apache.ddlutils", name: "ddlutils", version: "1.0"], files("$project.rootDir/lib/atgdust-1.2.2.jar") )
//------------------------- /** * Java compile dependencies. */ compile( files(dynamoclasspath.split(System.getProperty("path.separator")), "$project.rootDir/lib/testUtils-3.1.2.jar") )
//------------------------- /** * Java compilation configuration. */ compileJava {
// Save the compiler from re-compiling everything, even if only one // Java source file changes. options.useDepend=true
// Fork your compilation into a child process. options.fork = true
4 Using the Build System 35
} }
Logging Level for Unit Tests
The test script block sets the logging level for unit tests to ensure that meaningful reasons are returned for
failed tests. It also configures logging to record “PASSED” for unit tests that are successful.
test { testLogging { exceptionFormat 'full' events 'passed' }
Defining Common Tasks
The following section describes the Commerce Store Accelerator-specific tasks that are defined in the
allprojects closure of the root build.gradle script. These tasks are accessible to all Commerce Store
Accelerator build projects. Because task order in the build script matters, tasks are presented in this document in
the same order as they appear in the build.gradle script.
Note: A number of the following sections reference the project /build directory. A /build directory is created
within each project when you run Gradle and Gradles places its compiled classes, resources and JAR files in that
directory as part of its build process.
jshint
The jshint task runs the JSHint plugin to validate Commerce Store Accelerator JavaScript code for style
and formatting. If this task finds any errors, the build fails. For more information on JSHint, see http://
www.jshint.com/.
pluginsManifestBuilder
When you create an application module (for example, B2Cstore) you must include a gradle.properties file
in the module that defines an includedPlugins property. This property specifies the list of Commerce Store
Accelerator plugins on which the application depends, for example:
includedPlugins=\ CommerceAccelerator.Applications.B2CStore.Plugins.Account \ CommerceAccelerator.Applications.B2CStore.Plugins.Checkout \ CommerceAccelerator.Applications.B2CStore.Plugins.SearchAndNavigation \ CommerceAccelerator.Applications.B2CStore.Plugins.Spotlights \ CommerceAccelerator.Applications.B2CStore.Plugins.ShoppingCart \ CommerceAccelerator.Plugins.Preview \ CommerceAccelerator.Plugins.Checkout \ CommerceAccelerator.Plugins.Promotions \ CommerceAccelerator.Plugins.SEO
The pluginsManifestBuilder task then uses the includedPlugins property to create a MANIFEST.MF
file in the application module’s directory structure. For example, the following is the MANIFEST.MF file from
CommerceAccelerator/Applications/B2CStore/Plugins/META-INF:
36 4 Using the Build System
Manifest-Version: 1.0ATG-Required: CommerceAccelerator.Applications.B2CStore.Plugins.Accoun t CommerceAccelerator.Applications.B2CStore.Plugins.Checkout Commerce Accelerator.Applications.B2CStore.Plugins.SearchAndNavigation Commerc eAccelerator.Applications.B2CStore.Plugins.Spotlights CommerceAcceler ator.Applications.B2CStore.Plugins.ShoppingCart CommerceAccelerator.P lugins.Preview CommerceAccelerator.Plugins.Checkout CommerceAccelerat or.Plugins.Promotions CommerceAccelerator.Plugins.SEO
Note that each line length in the manifest is limited to 72 bytes to conform to standard JAR file specifications.
Any lines longer than 72 bytes are continued on the next line and must start with a single space.
composeDeployFromBaseAndPlugins
The composeDeployFromBaseAndPlugins task, in conjunction with the composeDeployFromEacTemplates
task, creates the deployment templates for the EAC applications that will support your Commerce Store
Accelerator application module.
To begin, the composeDeployFromBaseAndPlugins task creates a CommerceAccelerator/
Applications/CSA-application-name/src/main/deploy/EAC-application-name/ directory
for each EAC application. These directories hold the deployment template for each EAC application. The
number of directories to create, and their names, are defined by the eacApplications property in the /
CommerceAccelerator/Applications/CSA-application-name/gradle.properties file. For example,
the B2CStore application defines the following EAC applications in its gradle.properties file:
eacApplications=\ CSAde,\ CSAen,\ CSAes
After creating the EAC application directories, the composeDeployFromBaseAndPlugins task copies
deployment template fragments from the Base module and each included plugin into those directories. To
determine which plugins contribute to the deployment, the composeDeployFromBaseAndPlugins task
references the includedPlugins property specified in the application’s gradle.properties file. The source
files that composeDeployFromBaseAndPlugins copies from are found in the CommerceAccelerator/Base/
src/main/deploy and CommerceAccelerator/Plugins/plugin/src/main/deploy directories.
composeDeployFromEacTemplates
The composeDeployFromEacTemplates task, in conjunction with the composeDeployFromBaseAndPlugins
task, creates the deployment templates for the EAC applications that will support your Commerce Store
Accelerator application module. Specifically, the composeDeployFromEacTemplates task copies deployment
template fragments from two locations:
• From this source:
/CommerceAccelerator/Applications/CSA-application-name/src/main/eac-templates/common
To each of the EAC application deploy directories:
/CommerceAccelerator/Applications/CSA-application-name/src/main/deploy/EAC-
application-name
The /common source directory contains configuration settings that remains consistent across all EAC
applications and its contents are copied into each EAC application deploy directory. If you need to specify EAC
4 Using the Build System 37
application configuration settings that are the same across all your EAC applications, put them in the /common
source directory.
• From this source:
/CommerceAccelerator/Applications/CSA-application-name/src/main/eac-templates/EAC-
application-name
To the corresponding /CommerceAccelerator/Applications/CSA-application-name/src/main/
deploy/EAC-application-name directory. The source /EAC-application-name directories contain
configuration settings, namely /content and /pages, that are specific to the individual EAC applications.
The /CommerceAccelerator/Applications/CSA-application-name/src/main/deploy directory is
deleted each time a Gradle build is run, so you must put your EAC application configuration into the correct
source directories, from which it may be copied to the /deploy directory.
Also, note that each EAC application requires a deploy.xml file, located in /CommerceAccelerator/
Applications/CSA-application-name/src/main/deploy/EAC-application-name, in order to deploy
the application to the Workbench.
bowerInstall
The bowerInstall task allows Gradle to install Bower by invoking the bower install command from the
command line. The uiInstall task uses the bowerInstall task when it installs the third-party libraries that
modules with web applications depend on. This task is an Exec task.
bowerClean
The bowerClean task removes the bower_components directory from current project. This task should be used
whenever Bower component versions have been updated to ensure that the old versions get removed and
version conflicts do not occur. For example, if a version of Knockout gets updated in the bower.json file, this
task ensures that the old version of Knockout gets removed.
npmInstall
The npmInstall task allows Gradle to install Node by invoking the npm install command from the
command line. The uiInstall task uses the npmInstall task when it installs the third-party libraries that
modules with web applications depend on. This task is an Exec task.
uiInstall
The uiInstall task runs installer commands for the third-party libraries that modules with web applications
depend on. Specifically, this task runs the bowerInstall and npmInstall tasks to install Bower and Node.
If a module has a package.json file, uiInstall invokes the npmInstall task for that module, using
the configuration specified in the package.json file. Out of the box, the only module that includes a
package.json file is the root CommerceAccelerator module.
Similarly, if a module has a .bowerrc file, uiInstall invokes the bowerInstall task for that module, using
the configuration specified in the .bowerrc file. For example, the CommerceAccelerator/Base module
contains a .bowerrc file that specifies the Bower configuration for the CommerceAccelerator/Base/src/
main/web-app.
all
The all task allows you to invoke all the required tasks to build Commerce Store Accelerator with the command
gradle all.
38 4 Using the Build System
cleanAll
The cleanAll task removes a project’s /build directory along with any classes, resources, and JAR files it
contains.
cleanDeploy
The cleanDeploy task removes the EAC application deployment templates by deleting
the contents of the Commerce Store Accelerator application’s /deploy directory. See the
composeDeployFromBaseAndPlugins (page 36) and composeDeployFromEacTemplates (page 36)
sections for more details on the /deploy directory.
copyClasses
The copyClasses task copies compiled Java classes from a project’s build directory (for example,
CommerceAccelerator/Applications/<application>/build) into the project’s classes directory (for
example, CommerceAccelerator/Applications/<application>/classes). This task depends on the Java
plugin’s compileJava task completing first.
copyLibs
The copyLibs task copies the assembled JAR file from a project’s build directory (for example,
CommerceAccelerator/Applications/<application>/build) into the project’s lib directory (for
example, CommerceAccelerator/Applications/<application>/lib). ). This task depends on the Java
plugin’s assemble task completing first.
buildWar
The buildWar task assembles the store.war implementation, including third-party libraries as well as custom
JavaScript and HTML code, for a Commerce Store Accelerator application and places it in the application’s
CommerceAccelerator/Applications/<application>/src/main/j2ee-apps directory. Because this
assembly process is application-specific, the buildWar task in the root project is empty. You should override
the buildWar task implementation in the build.gradle file of your Commerce Store Accelerator application’s
module. The empty buildWar task is defined in the root build.gradle file so that it can be invoked from the
all task.
runGrunt
The runGrunt task is used to invoke the grunt command-line execution task. When the current working
project contains a src/main/web-app directory, a custom grunt Exec task is executed. This task adds the grunt
task named gradle to the argument list, thereby telling the grunt Exec task to run the gradle task that has
been defined in the CommerceAccelerator/.Gruntfile.js configuration. The gradle task is used to run
additional grunt tasks that compile and optimize Commerce Store Accelerator’s JavaScript.
The optimize task takes an application module’s individual .js files and merges them into a single, large
JavaScript file. This allows the browser to load the site using a single request, as opposed to hundreds of
requests for the individual JavaScript files. The list of files to merge is specified in the include array of an
application module’s Gruntfile.js file (CommerceAccelerator/Applications/application-name/
Gruntfile.js).
The compile task runs two additional tasks, customizeBootstrap and less, both of which are defined
in CommerceAccelerator/Base/Gruntfile.js. Bootstrap contains a number of source .less files (for
example, alerts.less, badges.less, navbar.less, and so on) that contain styles for the various Bootstrap
components. It also contains a bootstrap.less file that imports the constituent .less files. In order to
customize Bootstrap without modifying the original source files, Commerce Store Accelerator has its own
4 Using the Build System 39
versions of the .less files that need modification. These custom .less files first import the original .less file,
then modify the styles. The customizeBootstrap grunt task creates a new bootstrap.less file that replaces
the import paths for any overridden .less files. The less task compiles all .less files into .css files.
Creating Sub-Modules
When a task or configuration closure is too project-specific for the allprojects property closure in the root
build.gradle script, it should be added to a sub-module’s build.gradle file instead.
All sub-modules must define their own project location along with any project compile dependencies in the
build.gradle file. For example, the CommerceAccelerator/Applications/B2CStore/Base project has a
compile dependency on the CommerceAccelerator/Base module:
project(":Applications:B2CStore:Base") { defaultTasks "all"; description = "Project that extends all of the core CSA/Base functionality."
dependencies { compile project(":Base")
testCompile( files("${installationProjectPath}/src/test/java"), ) }}
For sub-modules that have WAR files, the build.gradle file should also extend the buildWar task to
provide application-specific configuration for assembling the application’s WAR file. For example, the
CommerceAccelerator/Applications/B2CStore module’s build.gradle file modifies the buildWar
task so that it copies the contents of the CommerceAcclerator/Applications/B2CStore/src/main/web-
app directory into a new store.war directory and then copies the relevant jars from the Oracle Platform to the
store.war/WEB-INF/lib directory.
The defaultTasks statement specifies that, if you run the gradle command for this module without
specifying a particular task, the gradle all task will run by default.
Creating Unit Tests for Your Modules
Gradle has the ability to execute unit tests as part of the build process. To set up a unit test for a Java source file,
you need to create a corresponding Java test file in /src/test/java. For example, if you have a /src/main/
java/atg/commerce/MyClass.java source file, you need to define a /src/test/java/atg/commerce/
MyClassTest.java test file. Unit tests are run as part of the Gradle Java plugin’s test task and can be written
using normal JUnit 4 and Oracle Commerce conventions. See the Java plugin documentation for more details
about the test task:
http://www.gradle.org/docs/current/userguide/java_plugin.html
40 4 Using the Build System
Building New Commerce Store Accelerator Modules
The Creating Commerce Store Accelerator Modules (page 15) chapter describes how to use the Gradle build
system to create a simple application module and simple plugin module using module templates provided with
the distribution. As you begin to create more complex new modules of your own, keep in mind that you may
have to consider the following tasks.
• Make sure dynamoHome is set. See setDynamoHome (page 32).
• Create the new module’s directory in the correct location:
• For application modules, create a CommerceAccelerator/Application/application_name directory.
• For a plugin module, create a CommerceAccelerator/Plugins/plugin_name directory.
Use the templates provided to populate these directories. See the Creating Commerce Store Accelerator
Modules (page 15) chapter for details.
• Add the new module to the include script block in the settings.gradle file in the root
CommerceAccelerator module. See Specifying the Modules to Include in the Build (page 30).
• Define any build properties required by your new module. See Defining Build Properties (page 31).
• Create the /src/main/java and /src/main/resources directories in your new module and place your
Java class files and resource files in them. See Java Source Code and Resource File Locations (page 34).
• Create the /src/test/java directory and populate it with any unit tests you want to run as part of the build.
See Creating Unit Tests for Your Modules (page 39).
• For application modules:
• Define the list of plugins to be included in the application module in a project-specific
gradle.properties file. See pluginsManifestBuilder (page 35).
• Add a buildWar task implementation to the project-specific gradle.properties file for that application.
See buildWar (page 38).
• For modules that must contribute to the deployment templates used to create any supporting EAC
applications, create the deployment template fragments in the correct locations as described in
composeDeployFromBaseAndPlugins (page 36) and composeDeployFromEacTemplates (page 36).
After building the new module, you must stop and remove the affected Oracle Commerce server instances, add
the new module to them in the appropriate startup location, and then re-assemble and re-deploy the server
instances. You can use Dynamo Server Admin to verify that your new module is running. Start Dynamo Server
Admin for the appropriate server. On the Dynamo Server Admin home page, click the Running ATG Products
link. Verify that your module exists in the running modules list.
IDE Integration
Gradle includes two plugins that allow you to integrate the Gradle build system with either the Eclipse or the
Intellij IDE, allowing you to build Commerce Store Accelerator projects using one of these popular development
tools. For more details, refer to the following links:
4 Using the Build System 41
http://www.gradle.org/docs/current/userguide/eclipse_plugin.html
http://www.gradle.org/docs/current/userguide/idea_plugin.html
42 4 Using the Build System
5 Client-side Routing in a Single-Page Application 43
5 Client-side Routing in a Single-Page
Application
The defining feature of single-page applications is the elimination of unnecessary loading and unloading of
pages, in an effort to enhance the user experience and improve performance. To control the loading of new
content whenever a new URL is requested, Commerce Store Accelerator incorporates a client-side router that
can be customized to return content as needed. This chapter describes how the client-side router works. It
includes the following sections:
Client-side Routing Overview (page 43)
Detecting Requests for Specific URLs (page 44)
Detecting Requests for Arbitrary URLs (page 45)
Commerce Store Accelerator’s Out of the Box Use of changestate (page 45)
Client-side Routing Overview
To manage page loading, the client-side router must:
• Provide a means of manipulating the browser URL, without causing the page to be automatically loaded.
• Detect requests for arbitrary URLs (for example, clicking the back or forward button), hijack those requests,
and manage the responses to them.
• Detect requests for specific URLs (for example, clicking a product link), hijack those requests, and manage the
responses to them.
Normally, when a page link is clicked or a form is submitted, the current page is unloaded and a new page is
loaded. Unloading the page means that all state associated with that page, including the HTML markup, CSS and
JavaScript state, is destroyed and must be rebuilt for the next page that is loaded. Commerce Store Accelerator
circumvents this normal flow, allowing the state to be preserved and the application developer to control
what content is loaded for the new URL. To circumvent the normal flow, Commerce Store Accelerator uses a
combination of the following:
• Extended versions of the History API’s history.pushState() and history.replaceState() functions,
defined in /CommerceAccelerator/Base/src/main/web-app/history.js script.
• An instance of the Crossroads router, created by the /CommerceAccelerator/Base/src/main/web-app/
router.js script.
44 5 Client-side Routing in a Single-Page Application
Detecting Requests for Specific URLs
The pushState() and replaceState() functions are responsible for updating the browser history
when a new URL is requested; pushState() adds a new entry to the browser history for the URL while
replaceState() replaces the current entry. In their native form, pushState() and replaceState() only
modify the browser history, they do not trigger a page load for the new URL. Commerce Store Accelerator
extends pushState() and replaceState() with an additional parameter, triggerPushStateEvent. When
triggerPushStateEvent is true, one of the following events is triggered:
• The pushstate event is triggered for the pushState() function.
• The replacestate event is triggered for the replaceState() function.
Both of these events trigger a subsequent changestate event. In the router.js script, an instance of the
Crossroads router is created and integrated with the changestate event, allowing the router to be notified
when a changestate event occurs.
// Create a router instance var router = crossroads.create(); window.addEventListener('changestate', function (e) { // Notify the router of the URL change router.parse(e.detail.URL);
After the router is notified, you can use the Crossroads API to match the pattern of the current URL to code you
would like to execute, for example:
router.addRoute('/cart', function () { alert('Cart page loaded');});
Note that Crossroads is only the mechanism for URL pattern matching and does not itself detect URL changes in
the browser. For that, Crossroads must be integrated with the changestate event, as shown above.
In order to invoke the extended versions of pushState() and replaceState(), Commerce Store Accelerator
must hijack the request first. Specifically, the history.js script listens for two types of events:
• Click events for anchor tags:
$(document).on('click', 'a:not([data-bypass],[target])', function (event) { });
Note: Anchor tags with the attribute data-bypass or target are not hijacked and behave as normal links,
loading content from the URL. The purpose of the data-bypass attribute is to give application developers
a simple and explicit mechanism to bypass the router. The target attribute normally causes the URL to be
open in a new tab or window, so it does not make sense to hijack these links because the current window is
not reloaded anyway.
• Submit events for HTTP GET forms:
$(document).on('submit', 'form[method="GET"]', function (e) { });
Note: POST forms are never hijacked. POST actions effect state change and re-running POST actions, for
example, purchasing an order, may cause unexpected or undesirable side effects.
When it detects one of these two event types, history.js hijacks the request by suppressing the default page
loading behavior:
5 Client-side Routing in a Single-Page Application 45
e.preventDefault();
Then history.js calls the extended version of either pushState() or replaceState(). If the new URL is the
same as the current URL, replaceState() is called, otherwise pushState() is called. Using replaceState()
avoids the scenario where a user clicks the same link multiple times. Instead of creating multiple, identical
entries in the history, a single entry for the link is created.
if (URL === window.location.href) { window.history.replaceState(null, null, URL, true);}else { window.history.pushState(null, null, URL, true);}
Detecting Requests for Arbitrary URLs
Detecting forward and back button clicks uses a similar technique to that used for specific URLs. When either of
these buttons is clicked, a popstate event is triggered. The history.js script listens for popstate events and,
when one occurs, it triggers a changestate event. From this point forward, the process is the same. The router
detects the changestate event and manages the response.
Commerce Store Accelerator’s Out of the Box Use of
changestate
The Crossroads router and API is provided for those developers who are building applications on top of
Commerce Store Accelerator and need to exercise more control over the response to URL change requests. Out
of the box, however, Commerce Store Accelerator only goes through the process of creating a Crossroads router
instance and notifying it of the URL change. It does not introduce any custom logic using the Crossroads API and
its pattern matching techniques. Instead, Commerce Store Accelerator simply triggers a re-loading of the view
model for the newly requested URL. When the view model for the page is loaded, any changes in the model data
is detected by Knockout. Through the use of Knockout bindings, the areas of the page that are associated with
the changed data are subsequently updated.
// When the state changes window.addEventListener('changestate', function (e) { // Notify the router of the URL change router.parse(e.detail.URL);
// Notify the view model of the URL change viewModel.load(e.detail.URL); });
See https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history for
details on the History API.
46 5 Client-side Routing in a Single-Page Application
6 Translating UI Strings 47
6 Translating UI Strings
This chapter describes how Commerce Store Accelerator handles translations of strings in its UI elements. It
includes the following sections:
Translating UI Strings (page 47)
UI String Translation Overview (page 47)
Configuring the i18next Library (page 48)
Loading the Resource File for the Current Language (page 48)
Retrieving Translated Strings (page 49)
Copying Source Translation Files during the Build Process (page 49)
Extending Translation Resources (page 50)
UI String Translation Overview
To accommodate cartridge renderers that have UI strings that require translation, Commerce Store Accelerator
has implemented:
• A RequireJS loader plugin called i18n-loader. A cartridge renderer’s view model uses the i18n-loader
plugin to load the translation resource file the renderer needs as a dependency. The resource file that gets
loaded is based on the current language.
• A custom Knockout filter called i18n-filter. This filter is added to text bindings in the cartridge renderer’s
HTML template and it is used to retrieve translated strings from the loaded resource file during page
rendering.
Both the loader plugin and the filter make use of the 18next third-party library:
• Before cartridge rendering, the i18n-loader uses the i18next library to locate and load the correct
translation resource file for the current language.
• During cartridge rendering, the i18n-filter uses the i18next library to locate and return the correct string
from the loaded resource file, after which the string is injected into the rendered HTML on the page.
The loader plugin and the filter are included as part of the Base module in /CommerceAccelerator/Base/
src/main/web-app/i18n-loader.js and i18n-filter.js, respectively.
48 6 Translating UI Strings
Configuring the i18next Library
As part of its tasks, the i18n-loader initializes and starts the i18next library. Before doing so, the i18n-
loader configures the i18next options, including:
• The name of the cookie, in this case language, that the i18next library should refer to when determining
the current locale. For an anonymous user, the language cookie defaults to English. For a registered user,
the cookie defaults to the user’s preferred language, as defined in the user’s profile. The value of the cookie
changes if the user chooses a new language in the language picker.
• The default language to use when the current language cannot be identified. Out of the box, the default
language is English.
• A template for the path the i18next library uses to locate the correct language-specific resource file for the
cartridge renderer.
Loading the Resource File for the Current Language
The i18n-loader uses the i18next library to calculate the path to the correct resource file for the current
language and then load it. The i18next uses the following template to calculate the path:
{{ns}}/translation_{{lng}}.json
{{ns}} represents a RequireJS namespace and {{lng}} represents a language. Using this template, i18next
calculates paths that look similar to the following, which locates the English translation resource for the
Account plugin module:
./bower_components/CSA.Plugins.Account/locales/translation_en.json
Replacing the {{ns}} Variable
As already mentioned above, the {{ns}} variable represents a RequireJS namespace that has been defined
for a Commerce Store Accelerator module. A RequireJS namespace is tied to a specific directory path through
configuration in the module’s main.js file.
Understanding how the namespace is calculated starts with the cartridge renderer view model. The view
model for a cartridge renderer that has translation resource dependencies must include the i18n-loader!
statement in its define code block. To describe how this statement behaves, we consider a specific example,
the AccountMenu.js file, which has the following i18n-loader! statement:
define([ 'content-item-mixin', 'text!AccountMenu.html', 'i18n-loader!AccountLocales.json', 'profile-services'], function (contentItemMixin, template, localeNamespace, profileServices) { }
The i18n-loader statement in this example instructs RequireJS to call the load() function of the i18n-
loader, passing in AccountLocales.json for the name parameter. The load() function strips off the .json
6 Translating UI Strings 49
portion of the name, leaving the namespace AccountLocales as the value for the name parameter. The load()
function calls the req.toUrl() function, passing in the name parameter, to convert the namespace to a URL. In
this case, the URL is converted to bower_components/CSA.Plugins.Account/locales, which is the value
defined for the AccountLocales namespace in the CommerceAccelerator/Plugins/Account/src/main/
web-app/main.js file.
At this point, the {{ns}} portion of the template path for the resource file to be loaded is known.
Loading the Language-specific Resource File
Once the value for the {{ns}} variable is determined, the i8n-loader calls the i18next.loadNamespace()
function. This function completes the template path using the language cookie to replace the {{lng}}
variable, resulting in a full path to the resource file, for example:
./bower_components/CSA.Plugins.Account/locales/translation_en.json
This file is then loaded and its resource strings are made available to the cartridge renderer’s HTML template.
Note that the key for each string is pre-pended with the namespace of the module, so that the label for a Close
button in one module can be distinguished from the label for a Close button in another module.
Retrieving Translated Strings
The HTML template for a cartridge renderer that has UI strings requiring translation will include statements
similar to the following:
{{ localeNamespace + ':button.account' | i18n }}
The double-curly braces of this statement are shorthand for identifying it as a Knockout text binding (this
shorthand is made possible through the use of the Knockout Punches library). The first part of the statement,
localeNamespace +, identifies the RequireJS namespace for the string that needs to be rendered. The
localeNamespace is set by the view model, using the value returned by the i18n-loader for the namespace,
and exposed for the HTML template’s use. The next portion of the statement, ':button.account', identifies
the key whose value must be returned. The combination of the two creates a fully qualified key for the UI
element.
The final portion of the statement, |18n, indicates that the fully qualified key should be passed to the i18n-
filter custom filter. The i18n-filter calls the i18next.t() function, passing it the fully qualified key. The
t() function locates the value for the passed key in the loaded resource file and returns the correct string.
Copying Source Translation Files during the Build Process
The locations that the RequireJS namespaces refer to are run-time locations, such as:
./bower_components/CSA.Plugins.Account/locales
The fully qualified path for this location resolves to something similar to the following:
50 6 Translating UI Strings
<ATG11dir>/CommerceAccelerator/Applications/application-name/src/main/j2ee-apps/
store.war/bower_components/CSA.Plugins.Account/locales
During the build process, Gradle copies the translation resources for a module from the module’s source /
locales directory to the run-time /locales directory. A module’s source /locales directory should use
the path module_name/src/main/web-app/locales. When creating a new module, be sure to add your
translation resource files to a directory that follows this structure and name them translation_lng.json
where lng is a two-letter language code. Create one translation_lng.json file for each language.
Extending Translation Resources
If you extend a Commerce Store Accelerator module, you may also need to extend its translation resources. The
translation resources should be placed in the extended module’s module_name/src/main/web-app/locales
directory so they are copied to the proper location in the run-time store.war file, as described in the Copying
Source Translation Files during the Build Process (page 49) section.
The HTML templates for cartridge renderers that belong to extended modules may need to distinguish between
the namespace associated with the extended module and the namespace for the unextended module. For this
case, the same process is used to calculate the extended module’s namespace and load its translation resource
file. However, instead of loading the extended module’s namespace into the localeNamespace property,
the cartridge renderer view models load the namespace into an appLocaleNamespace property. This allows
the HTML template to request strings from the unextended module, using localeNamespace, and strings
from the extended module, using appLocaleNamespace. For an example of this type of extension, see the
RefinementMenu.js and RefinementMenu.html files in these locations:
• Unextended module: <ATG11dir>/CommerceAccelerator/Plugins/SearchAndNavigation/src/
main/web-app
• Extended module: <ATG11dir>/CommerceAccelerator/Applications/B2CStore/Plugins/
SearchAndNavigation/src/main/web-app
Notice that the RefinementMenu.html in the extended module makes requests for strings from both the
localeNamespace and appLocaleNamespace namespaces.
7 Account Plugin 51
7 Account Plugin
This chapter provides an overview of the Account plugin, its UI components, and configuration. It includes the
following sections:
Account Plugin Overview (page 51)
Account Plugin UI Components (page 51)
Invoking the Account REST Services (page 54)
Account Plugin Configuration (page 54)
Account Plugin Overview
The CommerceAccelerator.Plugins.Account plugin module provides all functionality associated with
handling a shopper’s account, including:
• Creating and managing customer profiles
• Adding, editing, and deleting addresses
• Adding, editing, and deleting credit cards
The Account plugin also provides all of the necessary validation, error messaging, and REST services required to
work with these areas in a shopper’s account.
Note: The B2CStore application module includes the
CommerceAccelerator.Applications.B2CStore.Plugins.Account module to extend the functionality in
the out-of-the-box Account plugin with application-specific code and configuration.
Account Plugin UI Components
The view models (JavaScript files) and HTML renderers for the Account plugin module’s UI components
are defined in the CommerceAccelerator/Plugins/Account/src/main/web-app directory. Templates
for associated cartridges are located in CommerceAccelerator/Plugins/Account/src/main/deploy/
52 7 Account Plugin
import/templates. Note that not all UI components have associated cartridges; those that do not are marked
N/A in the Cartridge Type column of the table below.
UI Component Description Cartridge Type
AccountChangePassword Allows an authenticated user to change her
password. Shoppers are required to provide
their old password and confirm their new
one. If the old password is not correct or
confirmation of the new password fails then
the entire change password operation fails.
MainContent
AccountCheckoutDefaults Allows a shopper to set the default shipping
method, default shipping address, and
default payment method used during
checkout. The default shipping address and
default payment methods must have been
previously saved to the shopper’s profile.
New credit cards and addresses can be
added to the shopper’s profile so they can
be selected. The default shipping method is
selected from a set list of shipping methods
offered by the site.
MainContent
AccountMenu Displays a list of profile-related menu
options in the header. The options that are
displayed are different for anonymous users
versus logged in users. Once logged in,
the shopper can access his Address Book,
Payment Information, Order History, and
Checkout Defaults, and also change his
password.
HeaderAction
AccountMenuNavigation Displays a list of profile-related menu
options in the secondary content area,
for example, Personal Information, Order
History, Address Book and so on. The
options that are displayed are different for
anonymous users versus logged in users.
This cartridge also allows a shopper to log
out.
SecondaryContent
AccountOrderDetail Renders details about an order placed by a
customer, including the shipping and billing
information as well as the price and the
items purchased.
MainContent
7 Account Plugin 53
UI Component Description Cartridge Type
AccountOrderHistory Displays a simple summary view of all of
the past orders associated with the current
profile. The summary view displays the
order number, the site on which the order
was placed, the date the order was placed,
the number of items in the order, and the
current status of the order. By clicking an
order number, the shopper can navigate to
the Order Details page.
MainContent
AccountPersonalInformation Allows customers to modify their profile,
including email address (which is also the
login), first and last names, postal code,
gender, and birthday.
MainContent
AddAddress Allows a customer to add an address
to the list of addresses associated with
her profile. The address is saved in the
secondaryAddresses property on the
profile.
MainContent
AddCreditCard Allows a customer to add a credit card to the
list of credit cards associated with his profile.
The card is saved in the creditCards
property on the profile.
MainContent
EditAddress Allows a customer to edit a previously saved
address in the address book and specify the
default address associated with her profile.
MainContent
EditCreditCard Allows a customer to edit a previously saved
credit card in the list of credit cards and
specify the default credit card associated
with his profile.
MainContent
ForgotPassword Allows a shopper to request a password
reset. The ForgotPassword UI component
is rendered as part of the login page
(CommerceAccelerator/Plugins/
Account/src/main/web-app/login.js).
N/A
Login The Login cartridge serves multiple
purposes. It allows an anonymous customer
to become an authenticated customer by
logging in and it serves as the first step in
registering a new account.
MainContent
54 7 Account Plugin
UI Component Description Cartridge Type
RegisterUser Allows an unregistered customer to register
an account on the site. When registering, a
shopper is only required to supply a minimal
amount of information because the rest of
the shopper’s information is handled by
other cartridges.
MainContent
ViewAddressBook Allows a customer to view and delete
addresses associated with her profile.
MainContent
ViewPaymentInformation Allows a customer to view and delete credit
cards associated with his profile.
MainContent
Invoking the Account REST Services
The Account UI components use two JavaScript modules, profile-services and location-services,
to invoke REST services and communicate with the server through XHR requests. Both JavaScript modules
are found in CommerceAccelerator/Plugins/Account/src/main/web-app. The profile-services
JavaScript module returns profile information for the current customer. It also allows customers to manage their
address book and credit card information, log in, and log out. The location-services JavaScript module
returns a list of states for a given country code.
Account Plugin Configuration
This section describes required and optional configuration for application modules that use the Account plugin.
Required Application-specific Configuration for the Account Plugin
Some cartridges require a list of supported countries for the site. For example, the AddAddress cartridge needs
a list of countries to populate the Country drop-down menu. The list of supported countries is provided by the
/atg/store/shipping/PermittedCountries component, and this component should be configured on
a per-application module basis. The B2CStore application module configures this component as follows in
the CommerceAccelererator/Applications/B2CStore/src/main/config/atg/store/shipping/
PermittedCountries.properties file:
strings=\ CA, Canada,\ DE, Germany,\ MX, Mexico,\ US, United States
7 Account Plugin 55
Optional Application-specific Configuration for the Account Plugin
This section describes optional application-specific configurations you may choose to include for the Account
plugin.
Custom Date Formats
Some cartridges, such as the AccountPersonalInformation cartridge, require date formats. These cartridges
reference the /atg/store/i18n/CustomDateFormatter component to determine the pattern to be used
for dates. You can choose to specify custom dates for your application, for example, the B2CStore application
module specifies the following date formats for each locale in CommerceAccelerator/Applications/
B2CStore/Base/src/main/config/atg/store/i18n/CustomDateFormatter.properties:
customDateFormats=\ en=MM/dd/yyyy,\ de=dd.MM.yyyy,\ es=MM/dd/yyyy
If you do not specify any custom date formats, the format defaults to DateFormat.SHORT as defined by Java for
the customer’s locale.
Account Menu Links
The handler for the AccountMenu cartridge is of type LinkMenu, and it specifies a list of menu options (links)
that should be rendered for the Account menu. Because these links are application-specific, the configuration
for them should exist in the application directory. For example, the CommerceAccelerator/Applications/
B2CStore/Plugins/Account/src/main/config/atg/endeca/assembler/cartridge/handler/
AccountMenu.properties file configures the account menu to render different links for authenticated
shoppers and anonymous shoppers:
menuOptions=\ unauthenticatedMenuOptions=\ login=login,\ authenticatedMenuOptions=\ personalInformation=account:\ orderHistory=account/orders:\ addressBook=account/addressbook:\ paymentInformation=account/billing:\ changePassword=account/changepassword:\ checkoutDefaults=account/defaults
Access Controllers
Access control is used to manage access to a URL or REST service under certain circumstances; for example,
authenticated shoppers should be able to access URLs that unauthenticated shoppers cannot. There are two
accessor components, included in the Account module, that allow the application to determine if a shopper is
logged in or not:
• The CommerceAccelerator/Plugins/Account/src/main/config/atg/userprofiling/
NotLoggedInAccessController component references the /atg/targeting/
NotLoggedInRuleSetService component that resides in the CommerceAccelerator/Plugins/Account
module. The NotLoggedInRuleSetService component contains a rule to determine if the current shopper
is not logged in.
56 7 Account Plugin
• The CommerceAccelerator/Plugins/Account/src/main/config/atg/userprofiling/
LoggedInAccessController component references the /atg/targeting/LoggedInRuleSetService
component that resides in the CommerceAccelerator/Plugins/Account module. The
LoggedInRuleSetService component contains a rule to determine if the current shopper is logged in.
Determining if a shopper is logged in or not allows the application to restrict access to certain pages or REST
services to authenticated users only. To create these restrictions, the Account module configures access control
rules in the /atg/dynamo/servlet/dafpipeline/AccessControlServlet component. The rules provide
mappings between paths and the AccessController objects that control access to those paths. For example,
in the rules shown below, the LoggedInAccessController controls access to the /rest/model/atg/
userprofiling/ProfileActor/logout REST service, meaning that only shoppers who have logged in will be
able to access the REST service that logs them out.
accessControllers+=\ /rest/model/atg/userprofiling/ProfileActor/summary=\/atg/rest/userprofiling/LoggedInAccessController,\ /rest/model/atg/userprofiling/ProfileActor/logout=\/atg/rest/userprofiling/LoggedInAccessController,\ /rest/model/atg/userprofiling/ProfileActor/logout-success=\/atg/rest/userprofiling/AllAccessController,\ /rest/model/atg/userprofiling/ProfileActor/logout-error=\/atg/rest/userprofiling/AllAccessController
Because site URLs and REST services are often application-specific, application modules will likely need to
augment the rules provided in the Account module itself. For example, the B2CStore module configures the
following application-specific overrides in the CommerceAccelerator/Applications/B2CStore/Plugins/
Account/src/main/config/atg/dynamo/servlet/dafpipeline/AccessControlServlet.properties
file:
accessControllers+=\ /csa/login=/atg/userprofiling/NotLoggedInAccessController,\ /csa/account/register=/atg/userprofiling/NotLoggedInAccessController,\ /csa/account=/atg/userprofiling/LoggedInAccessController,\ /csa/account/orders/view=/atg/rest/userprofiling/AllAccessController
# The URL to redirect to if access is denied. If the AccessController# supplies its own deniedAccessURL, it will overwrite this value.deniedAccessURL=/csa/login
The B2CStore module also overrides the deniedAccessURL in both the NotLoggedInAccessController
and the LoggedInAccessController components. Because the LoggedInAccessController restricts
access to authenticated shoppers, this component redirects the shopper to the /csa/login page when access
is denied, providing the shopper with the ability to log in quickly. The NotLoggedInAccessController
redirects shoppers to the /csa/home page when access is denied.
8 Checkout Plugin 57
8 Checkout Plugin
This chapter provides an overview of the Checkout plugin, its UI components, and configuration. It includes the
following sections:
Checkout Plugin Overview (page 57)
Checkout Plugin UI Components (page 57)
Invoking the Checkout REST Services (page 58)
Checkout Plugin Configuration (page 59)
Checkout Plugin Overview
The CommerceAccelerator.Plugins.Checkout plugin module provides functionality that allows the
customer to:
• Check out an order, either as a registered customer or as a guest customer.
• Get confirmation of a successfully placed order and view order details.
Note: The B2CStore application module includes the
CommerceAccelerator.Applications.B2CStore.Plugins.Checkout module to extend the functionality
in the out-of-the-box Checkout plugin with application-specific code and configuration.
Checkout Plugin UI Components
The view models (JavaScript files) and HTML renderers for the Checkout plugin module’s UI components
are defined in the CommerceAccelerator/Plugins/Checkout/src/main/web-app directory. Templates
for associated cartridges are located in CommerceAccelerator/Plugins/Checkout/src/main/deploy/
import/templates. Note that not all UI components have associated cartridges; those that do not are marked
N/A in the Cartridge Type column of the table below.
58 8 Checkout Plugin
UI Component Description Cartridge Type
BillingAddressSelector Allows the shopper to specify a billing
address. Included in the Checkout UI
component.
N/A
Checkout Provides a single page checkout flow
where the customer can enter a shipping
address, shipping method, billing address,
and payment method. The Checkout
cartridge also allows the customer to enter
a coupon code and view a cart summary.
Upon completion of the required details,
the customer can submit the order.
MainContent
CheckoutCartSummary Provides a summary of items in the
shopper’s cart, including product display
name, color, size, and quantity. Included in
the Checkout UI component.
N/A
CheckoutLogin Provides the customer with options to
either login as an existing customer by
entering a username and password or
enter an email address and continue as a
guest customer. Upon entering either of
these valid details, the customer is taken to
the checkout page.
MainContent
OrderConfirmation Provides confirmation of a successfully
placed order and allows the customer to
click an order ID to see order details, print
the order details, or register for an account.
MainContent
PaymentMethodSelector Allows the shopper to specify a payment
method. Included in the Checkout UI
component.
N/A
ShippingAddressSelector Allows the shopper to specify a shipping
address. Included in the Checkout UI
component.
N/A
ShippingMethodSelector Allows the shopper to specify a shipping
method. Included in the Checkout UI
component.
N/A
Invoking the Checkout REST Services
The Checkout plugin includes the checkout-detail and checkout-services JavaScript modules. The
checkout-detail JavaScript module is a domain model that stores the checkout details for access by the other
JavaScript modules. The Checkout UI components use the checkout-services JavaScript module to invoke
8 Checkout Plugin 59
REST services and communicate with the server through XHR requests. Both JavaScript modules are found in
CommerceAccelerator/Plugins/Checkout/src/main/web-app.
Checkout Plugin Configuration
Beyond the steps required to include any plugin in an application, described in Adding an Out-of-the-Box Plugin
to an Application Module (page 21), there is no additional configuration required to include the Checkout
plugin. The B2CStore application module, however, implements an application-specific version of the
Checkout module that:
• Restricts access to the checkout page to logged-in shoppers or guest shoppers who have provided an email
address.
• Includes localized resource files for the shipping method labels (Ground, 2-Day, Overnight) presented in the
ShippingMethodSelector UI component.
The configuration associated with this additional functionality is described below.
AccessControlServlet
The AccessControlServlet, configured in CommerceAccelerator/Applications/B2CStore/Plugins/
Checkout/src/main/config/atg/dynamo/servlet/dafpipeline, controls whether customers can access
the checkout page. If a customer is logged in or is a guest that has provided an email ID on the checkoutlogin
page, the customer is allowed to view the checkout page. The servlet should be configured as follows:
# List of mappings between paths and AccessController objects. If a path refers# to a directory,all the documents in that directory and its subdirectories will# be protected by the given AccessController.
accessControllers+=\ /application-context-root/checkout=/atg/userprofiling/EmailAccessController,\ /application-context-root/checkout/checkoutlogin=\ /atg/rest/userprofiling/AllAccessController
EmailAccessController
The EmailAccessController component, configured in CommerceAccelerator/Applications/
B2CStore/Plugins/Checkout/src/main/config/atg/userprofiling, defines the rule set service to use
when determining whether access should be allowed to the checkout page. It also provides the URL to redirect
to if access is denied. It should be configured as follows:
$class=atg.userprofiling.RuleAccessControllerenabled=true
# Rules used to determine whether access should be allowedruleSetService=/atg/targeting/EmailRuleSetService
# URL to redirect to if access is denied
60 8 Checkout Plugin
deniedAccessURL=/checkout/checkoutlogin
EmailRuleSetService
The EmailRuleSetService component, configured in CommerceAccelerator/Applications/B2CStore/
Plugins/Checkout/src/main/config/atg/targeting, defines the rule that states a customer must have
an email address associated with her profile in order to view the checkout page. It should be configured as
follows:
$class=atg.targeting.RuleSetService$description=Defines rule set for access controller.
# The rule.ruleSet=<ruleset>\n <accepts>\n <rule op\=and tag\="Show">\n <rule op\=andtag\="Content">\n </rule>\n <rule op\=and tag\="Environment">\n <ruleop\=neq>\n <valueof target\="email">\n <valueof constant\="null">\n </rule>\n</rule>\n </rule>\n </accepts>\n</ruleset>
# Should we check whether the rules file has changed.updatesEnabled=true
# Time interval after which to check whether the rules file has# changed; if 0, the check will be performed on each request.rulesFileCheckSeconds=0
CheckoutResources
The B2CStore module includes default, English, Spanish, and German versions of the
CheckoutResource.properties resource file in CommerceAccelerator/Applications/B2CStore/
Plugins/Checkout/src/main/java/atg/projects/store. These files provide localized resource strings
for the shipping method labels (Ground, 2-Day, Overnight) presented in the ShippingMethodSelector UI
component.
9 Preview Plugin 61
9 Preview Plugin
This chapter provides an overview of the Preview plugin, its UI components, and configuration. It includes the
following sections:
Preview Plugin Overview (page 61)
Preview Plugin Configuration (page 62)
Preview Plugin Overview
The CommerceAccelerator.Plugins.Preview module provides the required functionality and configuration
to integrate both Experience Manager preview and Business Control Center preview into a Commerce Store
Accelerator application. Including the Preview plugin in an application gives a merchandiser the ability to
launch the application in preview mode from either the Business Control Center or Experience Manager.
Neither Experience Manager preview nor Business Control Center preview is included in the template for an
application module because preview functionality is not appropriate for all environments, for example, you
would not configure Business Control Center preview to run on a live production server. For this reason, the
configuration used to load the Preview plugin during server start up is found in the configuration layers
directories (CommerceAccelerator/Applications/application-name/src/main/configlayers) and
not the standard configuration directories (CommerceAccelerator/Applications/application-name/
src/main/config). You control the inclusion of a configuration layer with a server by passing the –layer
preview (for Business Control Center preview) or –layer endecapreview (for Experience Manager preview)
flags to the server during start up.
Business Control Center preview can be included with the following server types:
• basic_management
• basic_externalpreview
Experience Manager preview can be included with the following server types:
• basic_production (available when the Experience Manager Preview product add-on is selected for the
production server)
• production_lock (available when the Experience Manager Preview product add-on is selected for the
production server)
• basic_staging (available when the Experience Manager Preview product add-on is selected for the staging
server)
62 9 Preview Plugin
• staging_db (available when the Experience Manager Preview product add-on is selected for the staging
server)
Preview Plugin Configuration
To incorporate the Preview plugin into a Commerce Store Accelerator application, you must make sure
the application environment meets the requirements described below. Some requirements apply to both
Experience Manager and Business Control Center preview. Others apply to only one or the other and are marked
accordingly.
Server Instance Configuration in CIM
In order for the Preview plugin to work properly, your environment needs a staging server and a preview
server. The staging server serves the application that Experience Manager preview interacts with while the
preview server provides the preview functionality that is accessed through Business Control Center. Oftentimes,
the preview server is configured to run on the publishing server. Assuming this is the case, a full Preview
configuration would use publishing, staging, and production servers.
The following illustration shows how an environment incorporating the Preview plugin should be setup.
Specifically, this diagram illustrates that:
• The production server(s) should use the live Guided Search configuration, including the live EAC applications
(for example, CSAen, CSAde, and CSAes) and the live MDEX that supports those applications.
• The staging and publishing servers should use the staging Guided Search configuration, including the staging
EAC applications (for example, CSAStagingen, CSAStagingde, and CSAStaginges) and the authoring
MDEX that supports those applications.
9 Preview Plugin 63
To create this environment, in CIM you must do the following:
1. During product selection, in the CHOOSE ADDONS menu, include the Staging Server and Preview Server add
ons.
2. In the EXPERIENCE MANAGER PREVIEW OPTIONS SELECTION FOR STAGING, choose Configure Experience
Manager Preview to run on the Staging Server (do not configure Experience Manager Preview to run on the
Production Server)
3. In the PUBLISHING PREVIEW OPTIONS SELECTION Menu, choose Configure Preview to run on the CA Server.
4. During the publishing server instance configuration, set the following configuration:
• For the base EAC application name, specify the staging version of the base EAC application name, for
example, NewStoreStaging.
• For the default MDEX host and port, specify the staging server’s authoring MDEX host and port.
• For the local preview host and port, specify the publishing server’s host name and HTTP port.
• For the application configuration archive path for the default EAC application, specify the
archive path for the default staging EAC application, for example, /usr/local/endeca/Apps/
application_export_archive/NewStoreStagingen
IMPORTANT: The portion of this path up to but not including the EAC application name must match the
application configuration path provided during EAC application creation. This path is described in the EAC
Application Configuration (page 64) section below.
• Make sure the new application module is included in the server configuration by adding a custom
module, for example, CommerceAccelerator.Applications.NewStore, to the server after the
CommerceAccelerator.Base module.
5. During the production server instance configuration, set the following configuration:
• For the base EAC application name, specify the production version of the base EAC application name, for
example, NewStore.
• For the default MDEX host and port, specify the production server’s live MDEX host and port.
• For the application configuration archive path for the default EAC application, specify the
archive path for the default live EAC application, for example, /usr/local/endeca/Apps/
application_export_archive/NewStoreen
• IMPORTANT: The portion of this path up to but not including the EAC application name must match the
application configuration path provided during EAC application creation. This path is described in the EAC
Application Configuration (page 64) section below.
• Make sure the new application module is included in the server configuration by adding a custom
module, for example, CommerceAccelerator.Applications.NewStore, to the server after the
CommerceAccelerator.Base module.
6. During the Staging server instance configuration, set the following configuration:
• For the base EAC application name, specify the staging version of the base EAC application name, for
example, NewStoreStaging.
• For the default MDEX host and port, specify the staging server’s authoring MDEX host and port.
64 9 Preview Plugin
• For the application configuration archive path for the default EAC application, specify the
archive path for the default staging EAC application, for example, /usr/local/endeca/Apps/
application_export_archive/NewStoreStagingen
• IMPORTANT: The portion of this path up to but not including the EAC application name must match the
application configuration path provided during EAC application creation. This path is described in the EAC
Application Configuration (page 64) section below.
• Make sure the new application module is included in the server configuration by adding a custom
module, for example, CommerceAccelerator.Applications.NewStore, to the server after the
CommerceAccelerator.Base module.
EAC Application Configuration
During EAC application creation, you must provide the paths for the application configuration export archive
and the authoring application configuration export archive. The paths you enter must match the path you
entered for the default EAC application’s configuration archive path, up to but not including the EAC application
name, during the Oracle Commerce server instance configuration in CIM. For example, if during server instance
configuration in CIM, you entered:
/usr/local/endeca/Apps/application_export_archive/NewStoreStagingen
As the application configuration archive path for the default EAC application, then during EAC application
creation, you should enter:
/usr/local/endeca/Apps/application_export_archive
For the application configuration archive path and the authoring application configuration archive path.
IMPORTANT: Use forward slashes when entering these paths, even if on Windows.
Adding the Preview Plugin to the Application Module
Follow the steps described in Adding an Out-of-the-Box Plugin to an Application Module (page 21) to include
the Preview module in your application module. Note that, unlike the other plugins, the Preview plugin
should not be added to the Gruntfile.js configuration.
Modify the Application Module’s MANIFEST File
Add these two statements to CommerceAccelerator/Applications/application-name/META-INF/
MANIFEST.mf file. The first statement defines the configuration path for Business Control Center preview, the
second is for Experience Manager preview.
ATG-PreviewConfig-Path: src/main/configlayers/preview
ATG-EndecaPreviewConfig-Path: src/main/configlayers/endecapreview
Add the DynamoHandler.properties Files
As a security precaution, Commerce Store Accelerator applications are prevented from being loaded in an
iframe. However, both Experience Manager and Business Control Center preview load the site within an iframe,
so this configuration must be overridden in the preview configuration layers.
9 Preview Plugin 65
To override the iframe security configuration:
1. Copy the CommerceAccelerator/Applications/B2CStore/src/main/configlayers/preview/atg/
dynamo/servlet/dafpipeline/DynamoHandler.properties file.
2. Paste the copied file to these two locations; the first location is for Business Control Center preview. The
second is for Experience Manager preview.
CommerceAccelerator/Applications/application-name/src/main/configlayers/preview/atg/
dynamo/servlet/dafpipeline
CommerceAccelerator/Applications/application-name/src/main/configlayers/
endecapreview/atg/dynamo/servlet/dafpipeline
Enabling Business Control Center Preview from within Visual Merchandising
In order to be able to preview and edit site content from within Business Control Center using the Visual
Merchandising feature, you must configure the host and URL information used to access the site.
This step is required for Business Control Center preview only.
1. Copy these files in the CommerceAccelerator/Applications/B2CStore/src/main/config/atg/
dynamo/service/preview directory:
• CategoryPagePath.properties
• CategoryPageURL.properties
• HomePagePath.properties
• HomePageURL.properties
• Localhost.properties
• ProductDetailPagePath.properties
• ProductDetailPageURL.properties
2. Paste the copied files to the CommerceAccelerator/Applications/application-name/src/main/
config/atg/dynamo/service/preview directory.
3. Three of the files you pasted require modifications to change the context root specified in the preview paths.
Modify those files to insert your application module’s context root.
• In HomePagePath.properties:
defaultPath=/context-root/home
• In ProductDetailPagePath.properties:
defaultPath=/context-root/product?productId=$id
• In CategoryPagePath.properties:
defaultPath=/context-root/browse?categoryId=$id
66 9 Preview Plugin
Additional Configuration that Preview Depends Upon
The Preview module depends on some additional out-of-the-box configuration that is described below. You
do not have to do this configuration manually; however, you should be aware of it to better understand how
Preview works.
NucleusPreviewLinkServlet
The Preview module depends on the existence of the atg.endeca.servlet.NucleusPreviewLinkServlet
servlet in the application’s web.xml file. This servlet defines the NavigationStateBuilder and
WorkbenchContentSource components that Experience Manager preview uses to resolve the URLs for
previewed pages. The NucleusPreviewLinkServlet, shown below, already exists in the web.xml file that
is included in the module template located at CommerceAccelerator/module_templates/Application/
src/main/web-app/WEB-INF, so you do not have to add it manually as long as you have used the template to
create your application module.
<servlet> <servlet-name>link</servlet-name> <servlet-class>atg.endeca.servlet.NucleusPreviewLinkServlet</servlet-class> <init-param> <description> The Nucleus component path of the NavigationStateBuilder. </description> <param-name>navigationStateBuilderComponent</param-name> <param-value> /atg/endeca/assembler/cartridge/manager/NavigationStateBuilder </param-value> </init-param> <init-param> <description> The Nucleus component path of the ContentSource. </description> <param-name>contentSourceComponent</param-name> <param-value> /atg/endeca/assembler/cartridge/manager/WorkbenchContentSource </param-value> </init-param></servlet>
<servlet-mapping> <servlet-name>link</servlet-name> <url-pattern>/link.json/*</url-pattern></servlet-mapping>
Preview URLs in Experience Manager
The Preview module depends on the Default Preview URL, Preview URL , Default Link Service URL, and Link
Service URL defined for each EAC application in Experience Manager. The Preview URLs provide a fully qualified
URL for the application to be previewed. The Link Service URLs provide the URL of the service with your
application that constructs the links for preview.
These URLs are visible on the Preview Settings page in Workbench. They are populated using the preview
host, port, and context root you provide when you create and initialize an EAC application, so you do not have
to set the URLs manually in Experience Manager but you do have to provide the correct preview host, port,
and context root values during EAC application creation. Because the recommendation is to use Staging EAC
applications on the Staging server for Experience Manager preview, these URLs should reflect the Staging
server’s host name and port.
10 Promotions Plugin 67
10 Promotions Plugin
This chapter provides an overview of the Account plugin, its UI components, and configuration. It includes the
following sections:
Promotions Plugin Overview (page 67)
Promotions Plugin UI Components (page 67)
Invoking the Promotions REST Services (page 68)
Promotions Plugin Configuration (page 68)
Promotions Plugin Overview
The CommerceAccelerator.Plugins.Promotions plugin module provides a bridge between the
promotions created in the Business Control Center and an application based on the Commerce Store Accelerator
framework. If an application module includes the Promotions plugin, any promotions created in the Business
Control Center become available to the application. This includes both implicit promotions, which are
promotions that are automatically applied to a shopper’s cart when the cart satisfies a set of rules, or explicit
promotions that are applied after a customer enters a coupon code.
Promotions Plugin UI Components
The Promotions plugin includes a CouponEditor UI component that:
• Provides a coupon code entry field.
• Displays the promotions that have been applied to the order.
• Provides a Remove button that allows a customer to remove a coupon-based promotion.
The CouponEditor UI component is rendered as part of the shopping cart (CommerceAccelerator/Plugins/
ShoppingCart/src/main/web-app/CartEditor.js) and checkout (CommerceAccelerator/Plugins/
Checkout/src/main/web-app/Checkout.js) pages.
The view model (JavaScript file) and HTML renderer for the CouponEditor UI component is defined in the
CommerceAccelerator/Plugins/Promotions/src/main/web-app directory. This UI component is not
associated with an Experience Manager cartridge.
68 10 Promotions Plugin
Invoking the Promotions REST Services
The Promotions plugin includes a JavaScript module called promotions-services that invokes REST services
that apply a coupon to a shopper’s cart or remove a coupon from a shopper’s cart.The promotions-services
JavaScript module is found in CommerceAccelerator/Plugins/Promotions/src/main/web-app.
Promotions Plugin Configuration
This section describes required and optional configuration for application modules that use the Promotions
plugin.
Required Application-specific Configuration for the Promotions Plugin
Beyond the general steps for including a plugin in an application module, described in Adding an Out-of-
the-Box Plugin to an Application Module (page 21), there is no additional configuration required for the
Promotions plugin.
Optional Application-specific Configuration for the Promotions Plugin
You can choose to set the maximum number of coupons per profile that may be used at a time by setting the
maxCouponsPerProfile property on the /atg/commerce/claimable/ClaimableManager component. The
default value is 1.
11 SEO Plugin 69
11 SEO Plugin
This chapter describes the SEO plugin and its configuration. The SEO plugin encapsulates Commerce Store
Accelerator’s approach to search engine optimization (SEO). SEO makes pages more accessible to search bots
(also known as web spiders or crawlers), the scripts used by Internet search engines to crawl the Web to find
pages for indexing. The goal of SEO is to increase the ranking of the indexed pages in search results. This chapter
includes the following sections:
SEO Plugin Overview (page 69)
SEO Plugin Required Configuration (page 71)
SEO Plugin Overview
The SEO plugin incorporates functionality that enables the following SEO techniques:
• Sitemaps – XML files listing the URLs of all of the site’s pages, to make it easier for spiders to find the pages.
• Canonical links – HTML <link> tags for specifying SEO-friendly URLs for web spiders to record.
• SEO tagging – HTML <title> and <meta> tags for specifying search terms for indexing.
Sitemap Generation
Commerce Store Accelerator applications use the Oracle Commerce Guided Search sitemap generator for the
generating sitemaps that provide search bots with information about all of the content available on a site. All
applications based on the Commerce Store Accelerator code base should configure their application to use
the Guided Search sitemap generator as described in the Oracle Comerce Guided Search Sitemap Generator
Developer’s Guide.
Handling SEO Requests in a Single-Page Application
Search bots crawl site pages and index the pages based on content available in the HTML markup. Because
Commerce Store Accelerator is a single-page application based on JavaScript, the full HTML markup for any
given page is not available until after the JavaScript for the page has been processed. In order to provide a
search bot with the markup it needs, a Commerce Store Accelerator application pre-generates the HTML markup
for its pages, using the PhantomJS headless browser on the server side to execute the JavaScript. The pre-
generated content is stored in the SEORepository. Commerce Store Accelerator uses a servlet filter called
70 11 SEO Plugin
SEOFilter to identify search bot requests and then it retrieves the pre-generated HTML content from the
repository and returns it to the search bot. If the requested page does not exist in the repository, the HTML
content for it is generated, stored in the repository, and then served back to the search bot.
The SEOFilter, which is of class atg.filter.dspjsp.SEOFilter, uses two components, /atg/
repository/seo/UserAgentDetector and /atg/repository/seo/PhantomjsRenderer, to identify
search bot requests and render the complete markup for the requested URL. Both are configured as init-
params on the SEOFilter element in the application’s web.xml file.
The /atg/repository/seo/UserAgentDetector component is a request-scoped component of class
atg.repository.seo.UserAgentDetector. It has a browserType property, set to /atg/dynamo/servlet/
pipeline/BrowserTypes/Robot, that defines the pattern an incoming request must match to in order to be
considered a search bot request.
The /atg/repository/seo/PhantomjsRenderer component is of class
atg.repository.seo.PhantomjsRenderer which is an implementation of the
atg.repository.seo.MarkupRenderer interface. The MarkupRenderer interface requires that all
implementing classes have a getHtmlContent() method that gets the complete HTML markup for a page. The
PhantomjsRenderer class’s implementation of this method uses PhantomJS to perform the rendering. The
PhantomjsRenderer component has the following properties:
• waitTime: The amount of time, in milliseconds, that Commerce Store Accelerator waits for PhantomJS to
render the HTML for a page. Set this property to accommodate the maximum amount of time a complex page
on your site takes to render in PhantomJS. The default is 3000 milliseconds. Whatever markup is rendered at
the end of the waitTime time period is retrieved.
• phantomExecutablePath: The path to the PhantomJS executable file.
In order to boost performance, Commerce Store Accelerator pages are pre-rendered and their content is stored
in the SEORepository. When a search bot requests content for a page, Commerce Store Accelerator attempts
to retrieve the content from the SEORepository first. If the page does not exist in the repository, Commerce
Store Accelerator uses the PhantomJS headless browser to render the full HTML markup for the page, stores that
markup in the SEORepository for future reference, and then returns the markup to the search bot.
In order to populate the SEORepository with pre-genererated pages, Commerce Store Accelerator
uses two components. The /atg/endeca/sitemap/SiteLinksGenerator component, which is of
class atg.endeca.sitemap.SiteLinksGenerator, generates a complete list of site links for the
application. Then the /atg/repository/seo/SitemapPageCacheRenderer component, which is of class
atg.repository.seo.SitemapPageCacheRenderer, invokes the PhantomJS headless browser for each link
to generate the complete HTML markup and stores the pre-generated content in the SEORepository with the
page URL as the key.
Canonical Links
In a Commerce Store Accelerator application, the same content can be accessed in multiple ways using different
URLs. To prevent search bots from indexing duplicate content, a preferred URL, called a canonical URL, can be
specified for a page.
For any request that includes an Experience Manager cartridge handler (effectively, this is all requests), the
atg.endeca.assembler.event.SEOCanonicalLinkBuilder class is triggered during the content item
assembly process. This class adds a canonical link for the page to the content item with a key of canonical.
Canonical links generated by the SEOCanonicalLinkBuilder class take the following format.
Request scheme (http or https)
11 SEO Plugin 71
+://+Site server name+:+Site server port+Current site production URL, for example /csa/storeus+Content path, for example, /browse+Navigation State or Record State, depending on which is present. Navigation Stateare present for browse pages and Record States are present for product pages.
Any additional query parameters at the end on the Navigation or Record State are removed in order to create a
proper canonical link.
SEO Tagging
Web search engines base their rankings of pages partly on the words that appear in certain HTML tags,
particularly <meta> tags and the <title> tag. A common SEO technique is to list key search terms in those
tags, to raise the ranking of the pages for those terms.
The SEORepository holds the meta data for the pages in the rendered page cache. The meta data for the
product and category pages comes from the product catalog repository itself, specifically:
• The product or category title becomes the <title> tag for a product or category page.
• The product or category long description becomes the <meta name=description …> tag.
• The keywords for a product or category become the <meta name=keywords …> tag.
Because the meta tags are derived from the product catalog, it is important to make sure your product and
category items contain titles, long descriptions, and keywords. Out of the box, the cartridge renderers included
with Commerce Store Accelerator plugins add meta data and keywords to the content items they return.
SEO Plugin Required Configuration
This section describes required configuration for application modules that use the SEO plugin. Note that the
SEO plugin is not usable out of the box. All applications that use the SEO plugin must implement an application-
specific extension to the plugin to incorporate application-specific SEO configuration.
Configuring the Guided Search Sitemap Generator
All applications based on the Commerce Store Accelerator code base should be configured to use the Guided
Search sitemap generator as described in the Oracle Comerce Guided Search Sitemap Generator Developer’s Guide.
72 11 SEO Plugin
Installing PhantomJS
The PhantomJS headless browser is required to render the HTML returned for search bot requests. Download
and install PhantomJS from http://phantomjs.org/download.html.
Configuring the Application Module and SEO Plugin Extension
Follow the instructions below to create the SEO plugin extension and configure your application module to use
it and the parent SEO plugin.
1. Copy the SEO-related repository definition file and database SQL scripts to your application module:
• Copy the SEORepository.xml file located in CommerceAccelerator/Applications/B2CStore/src/
main/config/atg/seo to this location:
CommerceAccelerator/Applications/application-name/src/main/config/atg/seo
• Copy the csa_seo_ddl.sql file for your database type. This file is located in CommerceAccelerator/
Applications/B2CStore/src/main/sql/db_components/database-type, where database-type
is either db2, mssql, mysql or oracle depending on which database you are using.
Paste the csa_seo_ddl.sql file in this location:
CommerceAccelerator/Applications/application-name/src/main/sql/
db_components/database-type
• Copy the drop_csa_seo_ddl.sql file for your database type. This file is located in
CommerceAccelerator/Applications/B2CStore/src/main/sql/uninstall/database-type,
where database-type is either db2, mssql, mysql or oracle depending on which database you are
using.
Paste the csa_seo_ddl.sql file in this location:
CommerceAccelerator/Applications/application-name/src/main/sql/uninstall/database-
type
2. Create a directory for the SEO plugin extension called CommerceAccelerator/
Applications/application-name/Plugins/SEO/META-INF and populate it with a MANIFEST.MF file
that has the following content:
Manifest-Version: 1.0
ATG-Class-Path: lib/SEO.jar
ATG-Config-Path: src/main/config
ATG-Required: CommerceAccelerator.Applications.NewStore.Base
CommerceAccelerator.Plugins.SEO
3. To make the SEO plugin extension module start up with the rest of the application module, update the
CommerceAccelerator/Applications/application-name/META-INF/MANIFEST.mf file to add
CommerceAccelerator.Applications.application-name.Plugins to the ATG-Required property.
If, when adding this module name to the ATG-Required property, the line exceeds a length of 72 characters
ensure that all text after the 72nd character is wrapped onto the next line and the next line starts with a
space.
11 SEO Plugin 73
Note: This step may already have been done for other plugins that were included in the application module.
4. Create a build.gradle file in CommerceAccelerator/Applications/application-name/Plugins/
SEO with the following content:
project(":Applications:application-name:Plugins:SEO") {
defaultTasks "all";
description = "Contains cartridges, configuration and code
for the new feature."
dependencies {
compile project(":Plugins:SEO"),
project(":Base")
}
}
5. Create a StoreConfiguration component, using an identifying name such as
StoreUSConfiguration.properties, in CommerceAccelerator/Applications/application-name/
Plugins/SEO/src/main/config/atg/endeca/sitemap with the following content:
$description=Store configuration for generating site links.
$basedOn=StoreConfiguration
siteId=site-id
Each StoreConfiguration component provides the site ID for a store that should be included in the
generated sitemap.
6. Create a SiteLinksGenerator.properties file in CommerceAccelerator/
Applications/application-name/Plugins/SEO/src/main/config/atg/endeca/sitemap with the
following content:
$description=Extending the SiteLinksGenerator to add the storeSites
property.
# Sites for whick links has to be generated.
storeSites=/atg/endeca/sitemap/store-configuration-component-name
This configuration maps the component you created in the previous step to the storeSites property in the
SiteLinkGenerator component.
7. Create a PhantomjsRenderer.properties file in CommerceAccelerator/
Applications/application-name/Plugins/SEO/src/main/config/atg/repository/seo with the
following content:
# Phantomjs executable path.
phantomExecutablePath=path-to-phantomjs
Replace the path-to-phantomjs variable with the path to your PhantomJS executable, for example, C:/
phantomjs-2.0.0-windows/bin/phantomjs.exe.
8. Edit the CommerceAccelerator/Applications/application-name/gradle.properties file to add
the SEO plugin extension to the includedPlugins property.
includedPlugins=\
CommerceAccelerator.Applications.application-name.Plugins.SEO
9. Add the SEO plugin extension to the build by updating the CommerceAccelerator/settings.gradle file
to add the following reference at the end of the array:
74 11 SEO Plugin
"Applications:application-name:Plugins:SEO"
Be sure that all entries in the array end with a comma except for the last one.
10.If necessary, stop the production server instance.
11.In a UNIX shell or command prompt, change directories to the CommerceAccelerator directory.
12.Run the following command to execute the build:
gradle
13.Re-assemble and re-deploy the EAR file. You can do this using CIM by repeating the process for step [4]
Application Assembly & Deployment in the CIM main menu.
Testing the SEO Plugin Using Adhoc Search Bot Requests
To test the SEO plugin and the application-specific SEO plugin extension, you can create mock browser requests
that behave as if they are coming from a search bot. To do this, the User-Agent header in the request must be
modified to have a value of googlebot or some other search bot. One method for making these requests is to
use the Requestly plugin for Google Chrome.
To use Requestly to mock search bot requests:
1. Create a new rule in Requestly with the following characteristics:
Rule Name: SEO Test
Rule Description: Triggers the CSA SEO pipeline
Status: Active
Headers Modification Rules:
• Modify
• Request
• Header = User-Agent
• Value = googlebot
• Url Contains = /context-root/
11 SEO Plugin 75
2. Save the rule, making sure it is active.
3. Make sure the production server instance is running and make a request by navigating to the your site’s
home page, for example, localhost:8080/context-root/home.
4. Because the SEO Test rule is active, the request appears to come from a search bot. PhantomJS is called to
render the HTML content for the page and cache it in the SEORepository.
5. To confirm the page was rendered, in a browser, navigate to DynamoAdministration for the production
server, for example, http://localhost:8080/dyn/admin. Enter your user name and password.
6. Use the component browser to navigate to the /atg/seo/SEORepository component.
7. Click the List All Items link for the SEOPage repository item type. An SEOPage repository item matching the
URL you used in step 3 should appear in the list of items.
8. Once the testing is complete, be sure to deactivate the SEO Test requestly rule.
Populating the SEO Page Cache
Follow the instructions below to populate the HTML page cache in the SEORepository. How often you refresh
the data in the SEO page cache depends on your application’s requirements. However, you should be aware
that any time you do a baseline index and Experience Manager content promotion, the SEO page cache will no
longer be in synch with the live site until after you refresh the cache.
76 11 SEO Plugin
To populate the SEO page cache:
1. In a browser, navigate to DynamoAdministration for the production server, for example, http://
localhost:8080/dyn/admin. Enter your user name and password.
2. Search for the /atg/repository/seo/SitemapPageCacheRenderer component using the Search All
(Slow) option (because the component is not running all the time, navigating to it will not return results).
3. Click the generatePageCache link in the Methods section.
4. Click the Invoke Method button.
Note: The generatePageCache method can take time to execute. To terminate the method, you must stop
the server.
12 SearchAndNavigation Plugin 77
12 SearchAndNavigation Plugin
This chapter provides an overview of the SearchAndNavigation plugin, its UI components, and configuration.
It includes the following sections:
SearchAndNavigation Plugin Overview (page 77)
SearchAndNavigation Plugin UI Components (page 77)
Invoking the SearchAndNavigation REST Services (page 79)
SearchAndNavigation Plugin Configuration (page 79)
SearchAndNavigation Plugin Overview
The CommerceAccelerator.Plugins.SearchAndNavigation plugin module provides functionality that
allows the customer to:
• Search for a product or list of products by entering a particular keyword into a text box.
• View a list of products by clicking a category in the navigation menu.
• Refine searches using guided navigation functionality.
• View product detail pages.
Note: The B2CStore application module includes the
CommerceAccelerator.Applications.B2CStore.Plugins.SearchAndNavigation module to extend
the functionality in the out-of-the-box SearchAndNavigation plugin with application-specific code and
configuration.
SearchAndNavigation Plugin UI Components
The view models (JavaScript files) and HTML renderers for the SearchAndNavigation plugin module’s UI
components are defined in the CommerceAccelerator/Plugins/SearchAndNavigation/src/main/
web-app directory. Templates for associated cartridges are located in CommerceAccelerator/Plugins/
78 12 SearchAndNavigation Plugin
SearchAndNavigation/src/main/deploy/import/templates. The following table describes each of the
SearchAndNavigation UI components.
UI Component Description Cartridge Type
Breadcrumbs Presents the search terms and refinement
selections currently chosen by the shopper.
SecondaryContent
GuidedNavigation Displays the available refinement dimensions
to the shopper in the form of an array of
RefinementMenu UI components (described
below).
SecondaryContent
MainMenu Displays a menu in the header that allows the
shopper to choose a top-level category or a sub-
category that belongs to a top-level category.
HeaderContent
ProductDescription Renders the product description for the currently
viewed product.
ProductInformation
ProductDetail Retrieves the product ID stored in the MDEX and
uses it to query the catalog repository for product
properties. These properties are then used to
render the product detail page.
MainProductContent
RefinementMenu Presents valid follow-on refinement queries to the
shopper for a particular dimension.
Navigation
ResultsList Retrieves and manages search results from
the MDEX. Displays the returned products in a
paginated and sortable form.
MainContent
Search Allows the shopper to submit a search term
through an input field on an HTML form. When
the input field is empty, the Search button is
disabled. When the field contains text, the Search
button is enabled.
HeaderContent
12 SearchAndNavigation Plugin 79
UI Component Description Cartridge Type
SkuSelector Renders the SKU pickers that the shopper uses
to refine a product selection to a single SKU,
along with the quantity field and the Add to Cart
button. Also, ensures that a shopper’s selections
are valid before allowing the shopper to add the
selected item to the cart.
The SkuSelector UI component has a
runtime dependency on the addItemToOrder
function found in the cart-services
JavaScript module included with the
CommerceAccelerator.Plugins.ShoppingCart
plugin. This dependency facilitates the adding of
items to the shopper’s order.
If the
CommerceAccelerator.Plugins.ShoppingCart
plugin is not included in the same application
as this component, you must ensure that any
custom plugin that replaces the ShoppingCart
includes a Web services client that has an
addItemToOrder function that matches the API
of the addItemToOrder function found in cart-
services.
ProductInformation
Invoking the SearchAndNavigation REST Services
The catalog JavaScript module, located at CommerceAccelerator/Base/src/main/web-app/catalog.js,
is a domain model that stores the properties of the current product or currently selected SKU for access by the
other JavaScript modules.
The SearchAndNavigation plugin includes the catalog-services JavaScript module for invoking
REST services and communicating with the server through XHR requests. The plugin uses the catalog-
services module to retrieve product and SKU details from the catalog domain model in order to render the
product detail page. The catalog-services module can be found in CommerceAccelerator/Plugins/
SearchAndNavigation/src/main/web-app.
SearchAndNavigation Plugin Configuration
This section describes required and optional configuration for application modules that use the
SearchAndNavigation plugin.
80 12 SearchAndNavigation Plugin
Results List Optional Configuration
In order to limit the number of properties returned for products and SKUs in the ResultsList content item,
the application module can specify the properties to be retrieved in the fieldNames property of the /atg/
endeca/assembler/cartridge/handler/config/ResultsListConfig component, for example:
fieldNames+=\ product.baseUrl,\ product.repositoryId,\ product.displayName,\ product.largeImage.url,\ sku.activePrice
subRecordFieldNames+=\ sku.activePrice
Using the above configuration, the product and SKU properties in the content item are returned in the following
format:
"product.repositoryId": [ "xprod2517"],"product.baseUrl": [ "atgrep:/ProductCatalog/clothing-sku/xsku2517_4"],"sku.activePrice": [ "36.000000"],"product.displayName": [ "Cargo Pants"],"product.largeImage.url": [ "/csadocroot/content/images/products/large/APP_CargoPants_large.jpg"]
The application module can also specify the sorting options to include for the results lists using the sorters
property of the /atg/endeca/assembler/cartridge/handler/config/ResultsList component.
sorters=\ /atg/endeca/assembler/cartridge/sort/Relevance,\ /atg/endeca/assembler/cartridge/sort/NameAscending,\ /atg/endeca/assembler/cartridge/sort/NameDescending,\ /atg/endeca/assembler/cartridge/sort/PriceAscending,\ /atg/endeca/assembler/cartridge/sort/PriceDescending
The sorters property specifies a number of sorter components, for example, the NameAscending component,
which specifies that the results list should be sorted according to the product’s display name property in
ascending order.
class=atg.projects.store.assembler.cartridge.handler.model.LocalizableSortOptionConfig$scope=request
12 SearchAndNavigation Plugin 81
# The default label.label=A-Z
# Sort by name ascending. In the case where items have the same name, sort# by price ascending.value=product.displayName|0||sku.activePrice|0
Out of the box, the label displayed for the NameAscending sorting option in the sort menu is A-Z, however, this
label should be locale-specific. To add a locale-specific label for this sort option, a localized resource is specified
using the localizedLabelKey property of the /atg/endeca/assembler/cartridge/handler/config/
ResultsList component.
# The localized resource label key.localizedLabelKey=sort.nameAZ
Main Menu Optional Configuration
The MainMenu cartridge, which displays a menu in the header that allows the shopper to choose a top-level
category or a sub-category that belongs to a top-level category, does not reference a StartEndDateValidator
component out of the box. A StartEndDateValidator component verifies that a category has a valid
start and end date in order to be displayed. An application module can include this type of verification by
overriding the startEndDateValidator property of the /atg/endeca/assembler/cartridge/handler/
CategoryNavigation component, for example:
# Validate top-level-categories/sub-categories by start/end date.startEndDateValidator=/atg/store/collections/validator/StartEndDateValidator
The StartEndDateValidator component shown in this example is located in the CommerceAccelerator/
Base module and contains the following configuration:
$class=atg.service.collections.validator.StartEndDateValidator
currentDate=/atg/dynamo/service/CurrentDatestartDatePropertyName=startDateendDatePropertyName=endDate
Refinement Menu Optional Configuration
The RefinementMenu cartridge, which presents valid follow-on refinement queries to the shopper for
a particular dimension, does not reference a StartEndDateValidator component out of the box. A
StartEndDateValidator component verifies that a refinement dimension value has a valid start and
end date in order to be displayed. An application module can include this type of verification by overriding
the startEndDateValidator property of the /atg/endeca/assembler/cartridge/handler/
RefinementMenu component, for example:
# Validate refinement dimension values by start/end date.startEndDateValidator=/atg/store/collections/validator/StartEndDateValidator
82 12 SearchAndNavigation Plugin
The StartEndDateValidator component shown in this example is located in the Commerce Accelerator Base
module and contains the following configuration:
$class=atg.service.collections.validator.StartEndDateValidator
currentDate=/atg/dynamo/service/CurrentDatestartDatePropertyName=startDateendDatePropertyName=endDate
The RefinementMenu component included in the B2CStore also overrides the rangeFilterBuilders and
skuPropertyNames properties to add the following application-specific SKU date range filtering:
# Endeca SKU DateRangeFilter list builder.rangeFilterBuilders=\ /atg/endeca/assembler/cartridge/manager/filter/\ RefinementMenuSkuDateRangeFilterBuilder
# SKU dimension names that should use SKU range filters. This# ensures that when all of a product's SKUs contain invalid date(s), only# the SKU refinements will be affected.skuPropertyNames=\ clothing-sku.color,\ clothing-sku.size,\ furniture-sku.woodFinish
With this configuration, the StoreRefinementMenuHandler.preprocess() method checks to see if the
refinement menu dimension currently being processed is in the skuPropertyNames list. If so, the method adds
the RefinementMenuSkuDateRangeFilterBuilder to the NavigationState component’s FilterState so
that the dimension being processed is filtered by sku.startDate and sku.endDate.
Price Range Refinements Configuration
Application modules that need to support price range refinements in their Price dimension (for example, $1 -
$10, $10 - $50, and so on) must configure price ranges using one of several methods. The B2CStore application
module configures price ranges so that they are auto-generated based on the prices of individual SKUs. The
following section describes this configuration in order to provide an example of one approach to price range
refinement generation.
product-sku-output-config.xml
A new sku.priceRange property is created as a non-auto-generated dimension in CommerceAccelerator/
Applications/B2CStore/src/main/config/atg/commerce/endeca/index/product-sku-output-
config.xml:
<item property-name="childSKUs"> <properties> <!-- Properties --> <property name="priceRange" output-name="sku.priceRange" is-dimension="true" autogen-dimension-values="false" is-non-repository-property="true" type="float" multiselect-type="multi-or" property-accessor=
12 SearchAndNavigation Plugin 83
"/atg/commerce/endeca/index/accessor/ActivePriceAccessor"/> … … … </properties></item>
PriceDimensionValueExporter.properties
The PriceDimensionValueExporter component, included in the DCS module, is the
primary component that implements automatic price range generation. This component
is of class atg.endeca.index.dimension.RangedValuesExporter, which extends
atg.endeca.index.PerApplicationExporter, and it contains a number of configuration settings that
control how the price range refinements are generated. The B2CStore module configures these settings in
CommerceAccelerator/Applications/B2CStore/src/main/config/atg/commerce/endeca/index/
PriceDimensionValueExporter.properties:
# The dimension name.dimensionName=product.price_range
# The specifier for the parent root dimval. If null, defaults to# dimension name.rootParentSpecifier=/
# The source output property name to create dimvals forsourceOutputPropertyNames=sku.priceRange
# The default string for manually specifying which ranges will be# used.# A simple example would be "*:1000,*:100,*:10"# which specifies that the top level should have facets which cover# a range of 1000, the middle 100, and the bottom 10.## One can also specify sub-ranges. For example: "*:1000,*:100,*:1,,5:5,,20:10"## As in the first example, it specifies the top range should have facets# that cover a range of 1000, a middle the covers a range of 100, but# the bottom tier is more complex. For low values, ranges should# cover 1, for values starting at 5 a range should cover 5, and # starting at# 10, a range should cover ten. This would result in facets like:# 0-1, 1-2, 2-3, 3-4, 5-10, 10-15, 15-20, 20-30, 30-40, 40-50, 50-60,# etc.defaultFacetDefinitionRangeTiersString=*:10,,0:10,,100:100,,500:250,,1000:500
# Always generate facet ranges, starting at zero.minimumFacetsValue=0.0
# Whether to add localized display names as multi-language synonyms.# This is generally not useful numeric ranges, but may be useful if# use verbal display-names.multiLanguageSynonyms=false
# Whether to stop exactly at the maximum encountered value. If true,# no bounded facet will have an ending point higher than the specified# price. If false, facets will end at the next normal boundary.stopExactlyAtMaxValue=false
# The dimval.range.comparison_type value. Use decimal for
84 12 SearchAndNavigation Plugin
# price-type numbers (the default). Other valid value would be# integer.dimvalNameComparisonType=decimal
# If true, use a language suffix ("_en" or "_es", for example) to# construct localized attribute names. If full, uses the complete# locale (such as "_en_US" or "_en_DE_EURO").useLanguageSuffix=false
ProductCatalogSimpleIndexingAdmin.properties
The PriceDimensionValueExporter component is added to the indexing job in CommerceAccelerator/
Applications/B2CStore/src/main/config/atg/commerce/endeca/index/
ProductCatalogSimpleIndexingAdmin.properties:
phaseToPrioritiesAndTasks+=\ RepositoryExport+=PriceDimensionValueExporter
SchemaExporter.properties
The PriceDimensionValueExporter component is added as a dimension name provider to
CommerceAccelerator/Applications/B2CStore/src/main/config/atg/commerce/endeca/index/
SchemaExporter.properties:
dimensionNameProviders+=\ PriceDimensionValueExporter
ProductCatalogOutputConfig.properties
The /atg/commerce/endeca/index/DynamicPriceValueSynchronization component (located in DCS)
is added to the indexingSynchronizations property of the CommerceAccelerator/Applications/
B2CStore/src/main/config/atg/commerce/search/ProductCatalogOutputConfig component so that
it can monitor price properties and invoke the PriceDimensionValueExporter after product and SKU records
have been generated:
indexingSynchronizations+=\ /atg/commerce/endeca/index/DynamicPriceValueSynchronization
index-config.json
To ensure that the correct indexing configuration properties are set for the new product.price_range
dimension, the following configuration is added to CommerceAccelerator/Applications/B2CStore/src/
main/deploy/index_config/index-config.json:
"product.price_range" : { "displayOrder" : 1, "mergeAction" : "UPDATE", "jcr:primaryType" : "endeca:dimension", "rangeComparisonType" : "FLOAT" }
12 SearchAndNavigation Plugin 85
initial_dval_id_mappings.csv
In order to have consistent price range dimension value IDs every time the deployment template is
executed, the CommerceAccelerator/Applications/B2CStore/src/main/deploy/test_data/
initial_dval_id_mappings.csv includes the following configuration:
"product.price_range","/","3494134414""product.price_range","product.price_range","2323533082""product.price_range","r0-10","2187310031""product.price_range","r10-20","566039580""product.price_range","r20-30","2131962054""product.price_range","r30-40","2481498198""product.price_range","r40-50","2961085591""product.price_range","r50-60","4219068011""product.price_range","r60-70","3437059647""product.price_range","r70-80","3588385073""product.price_range","r80-90","3639965157""product.price_range","r90-100","2299607508""product.price_range","r100-200","180223605""product.price_range","r200-300","3888546018""product.price_range","r300-400","3560702933""product.price_range","r400-500","1541355225""product.price_range","r500-750","4047109018""product.price_range","r750-1000","839602541""product.price_range","r1000-1500","1085939743""product.price_range","r1500-2000","3430508338""product.price_range","r2000-2500","3885777590""product.price_range","r2500-unbounded","3470947321"
GuidedNavigation content.xml
To include the product.price_range dimension in the Guided Navigation cartridge, it is added to
CommerceAccelerator/Applications/B2CStore/src/main/deploy/import/content/Web/Guided
Navigation/Default Guided Navigation/content.xml. To ensure that the price ranges within the
product.price_range dimension are displayed in a logical order in the store, they need to be ordered
properly in the boostRefinements property.
<ContentItem type="Navigation"> <TemplateId>RefinementMenu</TemplateId> <Name>Price Range</Name> <Property name="dimensionName"> <String>product.price_range</String> </Property> <Property name="dimensionId"> <String>3494134414</String> </Property> <Property name="sort"> <String>default</String> </Property> <Property name="showMoreLink"> <Boolean>false</Boolean> </Property> <Property name="moreLinkText"> <String>Show More Refinements...</String> </Property> <Property name="numRefinements"> <String>10</String>
86 12 SearchAndNavigation Plugin
</Property> <Property name="maxNumRefinements"> <String>200</String> </Property> <Property name="boostRefinements"> <List name="boost" xmlns="http://endeca.com/schema/xavia/2010"> <Item class="com.endeca.infront.navigation.model.DvalSpec"> <Property name="id">2187310031</Property> <Property name="name">$0.00 - $9.99</Property> </Item> <Item class="com.endeca.infront.navigation.model.DvalSpec"> <Property name="id">566039580</Property> <Property name="name">$10.00 - $19.99</Property> </Item> <Item class="com.endeca.infront.navigation.model.DvalSpec"> <Property name="id">2131962054</Property> <Property name="name">$20.00 - $29.99</Property> </Item>
…
<Item class="com.endeca.infront.navigation.model.DvalSpec"> <Property name="id">3885777590</Property> <Property name="name">$2,000.00 - $2,499.99</Property> </Item> </List> </Property> <Property name="buryRefinements"> <aaa:List xmlns:aaa="http://endeca.com/schema/xavia/2010"/> </Property> <Property name="displayNamePropertyAlias"> <String>displayName</String> </Property></ContentItem>
12 SearchAndNavigation Plugin 87
Product Details Page Configuration
The information displayed on the product detail page is driven by product and SKU properties and their values.
88 12 SearchAndNavigation Plugin
While the SearchAndNavigation plugin provides all of the required code and configuration to display product
name, description, price, and image for any type of product, the SKU pickers displayed for a product depend
on the type of product itself. For example, a clothing product might show options for picking color and size
while a furniture product might show options for picking wood finish. Because the SKU pickers on product detail
pages are so tightly tied to the underlying data, generic instructions for how to create them cannot be provided.
Instead, this section provides an example for you to follow by describing the code and configuration included in
the B2CStore module for rendering SKU pickers that are appropriate for its underlying sample data of clothing
and furniture products.
Defining SKU Types and Their Properties
To configure SKU pickers for a given site, the product detail page must know:
• The types of SKUs that belong to the products being displayed, for example, clothing SKUs and furniture SKUs.
• The properties belonging to these SKU types that will be used to create a SKU picker, for example, color and
size for a clothing SKU and wood finish for a furniture SKU. Note that these properties must match properties
defined for the SKU types in the catalog repository.
The B2CStore application module defines two SKU types: clothing-sku and furniture-sku. Two
components in the B2CStore module define the SKU properties that are used to create SKU pickers for these
two types, /atg/commerce/catalog/sku/properties/ClothingSkuProperties and /atg/commerce/
catalog/sku/properties/FurnitureSkuProperties. The properties files for these components are shown
below.
ClothingSkuProperties
12 SearchAndNavigation Plugin 89
$class=atg.projects.store.sku.SkuTypeProperties$scope=global$description=Properties component used to define clothing SKU-related propertiesallowing the property names to be configured in component property files.
# This is a list of properties that are used for building a SKU picker for this# SKU type.skuPropertyList=\ color,\ size
FurnitureSkuProperties
$class=atg.projects.store.sku.SkuTypeProperties$scope=global$description=Properties component used to define furniture SKU-related propertiesallowing the property names to be configured in component property files.
# This is a list of properties that are used for building a SKU picker for this# SKU type.skuPropertyList=\ woodFinish
Both components are of class atg.projects.store.sku.SkuTypeProperties, which is included in the
SearchAndNavigation plugin. This class contains a single property, skuPropertyList, that defines the SKU
properties that should be used to create pickers for the associated SKU type. In the case of B2CStore, color
and size properties are used to create SKU pickers for clothing SKUs while the woodFinish property is used to
create a SKU picker for furniture SKUs.
Informing the ProductDetails Cartridge Handler of the SKU Types
The content item that Experience Manager returns for the product detail page contains all of the information
required for the initial page load including all of the product’s properties, the skuTypes that the page must
handle, and the SKU properties that are used to build the SKU pickers for the individual skuTypes. The
cartridge handler for the product detail page, namely the /atg/endeca/assembler/cartridge/handler/
ProductDetails component, uses its skuTypes property to map each SKU type to the list of SKU properties
that should be used to create a picker for that type. For example, in the B2CStore, the skuTypes property
maps the clothing-sku to the properties list defined by /atg/commerce/catalog/sku/properties/
ClothingSkuProperties.skuPropertyList and the furniture-sku to the properties list defined in /atg/
commerce/catalog/sku/properties/FurnitureSkuProperties.skuPropertyList.
# Resolving Map that holds a map of the SKU types that will be served and any# unique properties that will be used for their corresponding SKU pickers.# The key for this map should be the identifier for the SKU type.skuTypes=\ clothing-sku^=/atg/commerce/catalog/sku/properties/\ ClothingSkuProperties.skuPropertyList,\ furniture-sku^=/atg/commerce/catalog/sku/properties/\ FurnitureSkuProperties.skuPropertyList
By including this configuration, additional SKU information is added to the content item to facilitate the
rendering of the SKU pickers, namely childSkuType and childSkuPickerProperties.
90 12 SearchAndNavigation Plugin
"mainProductContent": [{ "metadata": { "keywords": "silk,dry,suede,buttons,newest,clean,blazer,fall,town,leather,", "description": "Greet fall with our newest suede blazer. Dry clean only.", "title": "CSA Store - Suede Blazer"},"product": { "longDescription": "Greet fall with our newest suede blazer. Dry clean only.", "isAvailable": true, "salePrice": "84.0 - 99.0", "displayName": "Suede Blazer", "largeImageUrl": "/csadocroot/content/images/products/large/APP_SuedeBlazer_large.jpg", "repositoryId": "xprod2504", "childSkuType": "clothing-sku", "showSalePrice": false, "childSkuPickerProperties": [ "color", "size" ], "listPrice": "84.0 - 99.0"},
Note: The clothing-sku and furniture-sku types map to item-descriptors that are defined in the B2CStore
repository extensions.
Sku Picker Dependencies on B2CStore.Base Plugin Extensions
The SKU pickers described in the previous section also rely on some extensions made in the B2CStore.Base
module.
atg.projects.store.catalog.B2CStoreCatalogProperties
This class is an extension of the atg.projects.store.catalog.StoreCatalogProperties class included
in the Commerce Store Accelerator Base module and it adds a new catalog property called sizePropertyName
and sets its value to size. Instead of directly referencing the size property by name, other components use
the getSizePropertyName() method. This allows you to change the name of the size property in one
location, if necessary, without having to modify other code that uses the size property. The /atg/commerce/
catalog/custom/CatalogProperties component in the B2CStore.Base module is configured to use the
B2CstoreCatalogProperties class, thereby making the size property available to other components.
atg.projects.store.catalog.B2CstoreCatalogTools
This class is an extension of the atg.projects.store.catalog.StoreCatalogTools class included in
the Commerce Store Accelerator Base module and it provides the CatalogTools component with a number
of additional methods for sorting lists of colors and sizes. The /atg/commerce/catalog/CatalogTools
component in the B2CStore.Base module is configured to use this class. The component also defines the
sizeSortOrder property, which specifes the order in which lists of sizes should be presented. For B2CStore,
this order is:
sizeSortOrder=One Size,Small,Large,XS,S,M,L,XL,XXL,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42
Sorting for colors is done alphabetically.
12 SearchAndNavigation Plugin 91
Creating the SKU Pickers
The process used to determine a SKU based on selections made in a SKU picker is application-specific and is not
included in the SearchAndNavigation plugin out of the box. The role of a SKU picker is twofold. First, the SKU
picker is used to return a list of all available options for any child SKUs that exist for the product being rendered
on the product detail page. This information is included in the content item returned for the request along with
the rest of the product and SKU information. Secondly, the SKU picker responds to changes to the selected
options on the client and, using the available information, attemps to find the matching SKU and return it back
to the client. Several additional classes have been created in the B2CStore.Plugins.SearchAndNavigation
module to provide this functionality.
Based on the B2CStore catalog, the minimum number of SKU pickers that could be present on the product
detail page is 0, for a single SKU product, while the maximum is two, for a clothing SKU that has both color and
size pickers. To accommodate this situation, the following classes were created:
• atg.projects.store.sku.picker.DefaultSkuPicker: This abstract class contains common
functionality useful to all pickers and forms the basis of all SKU pickers in the B2CStore.
• atg.projects.store.sku.picker.ColorSkuPicker: This class extends DefaultSkuPicker and
contains the logic for both locating a product’s clothing-sku using the color selected in the SKU picker
and for returning a list of all available colors for a product. This class is also used for selecting a product’s
furniture-sku based on the selected woodFinish (described in further detail below).
• atg.projects.store.sku.picker.SizeColorSkuPicker: This class extends the ColorSkuPicker class
and contains the logic for both locating a product’s clothing-sku using the color and size selected in the
SKU picker and for returning a list of all available sizes for a product. (Note that this class only returns the list of
available sizes because the ColorSkuPicker class returns the list of available colors.)
The B2CStore.Plugins.SearchAndNavigation module configures a set of SKU picker components using
these classes.
ColorSkuPicker Component
The /atg/commerce/product/detail/ColorSkuPicker component
defined in the B2CStore.Plugins.SearchAndNavigation module is of class
atg.projects.store.sku.picker.ColorSkuPicker. The configuration for this component is shown below:
$class=atg.projects.store.sku.picker.ColorSkuPicker$scope=prototype$description=A component used to to control the behaviour of a SKU picker thatcontains color options.
# Instance of Catalog Tools.catalogTools=/atg/commerce/catalog/CatalogTools
# Instance of ProductDetailTools.productDetailsTools=/atg/commerce/product/detail/ProductDetailsTools
# Instance of skuPickerPropertyManager.skuPickerPropertyManager=/atg/commerce/product/detail/SkuPickerPropertyManager
The ColorSkuPicker component also contains three additional properties, which are not configured here
because appropriate defaults are specified for them in the class itself. These properties represent the keys that
are used to identify the color property, the selected color, and the available colors in the Map that is returned
from the server when a picker change is made on the client:
92 12 SearchAndNavigation Plugin
• colorPropertyName: Defaults to color.
• selectedColorPropertyName: Defaults to selectedColor.
• availableColorsPropertyName: Defaults to availableColors.
These properties do not need to be adjusted if you are configuring a SKU picker for use with colors but they can
be overriden to work with a different SKU property (for example, a wood finish property), as described in the
next section.
WoodFinishSkuPicker Component
Furniture SKUs in the B2CStore catalog can have a maximum of one SKU picker for selecting
the furniture’s wood finish. The /atg/commerce/product/detail/WoodFinishSkuPicker
component defined in the B2CStore.Plugins.SearchAndNavigation module is of class
atg.projects.store.sku.picker.ColorSkuPicker and its configuration is shown below:
$class=atg.projects.store.sku.picker.ColorSkuPicker$description=A component used to control the behaviour of a SKU picker thatcontains wood finish options.# Base this component on the ColorProductDetailsPicker component as they share# similar properties.$basedOn=ColorSkuPicker
# Override the color-related properties in order to make this picker target# the wood finish-related properties.colorPropertyName=woodFinishselectedColorPropertyName=selectedWoodFinishavailableColorsPropertyName=availableWoodFinishes
The WoodFinishSkuPicker extends the ColorSkuPicker component and inherits all of that component’s
properties. However, the WoodFinishSkuPicker overrides the default values of colorPropertyName,
selectedColorPropertyName, and availableColorsPropertyName to reflect the fact that this SKU picker
works with wood finish-related SKU properties instead. Specifically, it sets colorPropertyName to woodFinish,
selectedColorPropertyNames to selectedWoodFinish, and availableColorsPropertyName to
availableWoodFinishes.
SizeColorSkuPicker Component
Like the WoodFinishSkuPicker, the SizeColorSkuPicker component extends the ColorSkuPicker. Its
configuration is shown below:
$class=atg.projects.store.sku.picker.SizeColorSkuPicker$description=A component used to to control the behaviour of a SKU picker withsize and color options.
# Base this component on the ColorSkuPicker component as they share similar# properties.$basedOn=ColorSkuPicker
# Add 'One Size' (and its translations) to the helper property black list.helperPropertyBlackList=\ One Size
While the SizeColorSkuPicker component is based on the ColorSkuPicker component, it does override
the $class property to use atg.projects.store.sku.picker.SizeColorSkuPicker instead. This class
12 SearchAndNavigation Plugin 93
adds a number of additional properties that have defaults specified in the class definition. These properties
represent the keys that are used to identify the size property, the selected size, and the available sizes in the Map
that is returned from the server when a picker change is made on the client:
• sizePropertyName: Defaults to size.
• selectedSizePropertyName: Defaults to selectedSize.
• availableSizePropertyName: Defaults to availableSizes.
As with the ColorSkuPicker, these properties do not have to be set if the SKU picker being selected has color
and size properties. They can, however, be modified if required as demonstrated with the WoodFinishPicker
in the previous section. Some attention must be paid, however, if using this picker for other SKU types as some
unexpected sorting can happen unless it is managed properly in the class methods.
The helperPropertyBlackList property controls the display of the size chart hyperlink, which should be
suppressed if a product only has only one size. This property ensures that a size chart link is not displayed for a
product if the property values listed in the black list are the only values available to the picker. In other words, if
One Size is the only value available to the picker, do not display the size chart link.
Encapsulating the SKU Pickers and Controlling Access to Them
After the different types of SKU pickers required by the site are defined, they need a container to encapsulate
them and control access to them. The /atg/commerce/product/detail/SkuPickers component included
in the B2CStore.Plugins.SearchAndNavigation module fulfills these requirements. The SkuPickers
component encapsulates the SKU pickers in two different maps, shown below:
# Service map containing each of the available SKU pickers. These are keyed by# the unique SKU property name that a SKU picker would be generated for, for# example "color" for a clothing-sku.skuPickerMap=\ color=/atg/commerce/product/detail/ColorSkuPicker,\ size=/atg/commerce/product/detail/SizeColorSkuPicker,\ woodFinish=/atg/commerce/product/detail/WoodFinishSkuPicker
# Service map that maps a SKU type to a particular product picker. Used to# retrieve the correct SKU picker when a REST call is made from the client.skuTypeToSkuPickerMap=\ clothing-sku=/atg/commerce/product/detail/SizeColorSkuPicker,\ furniture-sku=/atg/commerce/product/detail/WoodFinishSkuPicker
The skuTypeToSkuPickerMap is keyed on the SKU item-descriptor which, in the case of B2CStore, is
clothing-sku or furniture-sku. The map is used to identify which SKU picker should be used to find a
matching SKU for the passed SKU property value(s). The SKU property values are passed through a REST request
whenever a change is made to a SKU picker on the product detail page in the browser.
The skuPickerMap is keyed on a SKU property which should match one of the properties defined in the
skuPropertyList of either the /atg/commerce/catalog/sku/properties/ClothingSkuProperties or
/atg/commerce/catalog/sku/properties/FurnitureSkuProperties components. This map is used by
the SkuSelector component, described below, to retrieve the correct SKU picker to use for generating a list of
all available options for the passed SKU property, for example, a list of all colors associated with the color SKU
property.
SkuSelector Cartridge Handler
While the /atg/endeca/assembler/cartridge/handler/ProductDetails cartridge handler handles the
addition of product (and some SKU) properties to the content item returned by the server, it does not include
94 12 SearchAndNavigation Plugin
the construction of data objects required for building and rendering SKU pickers on the product detail page.
This task is handled by the /atg/endeca/assembler/cartridge/handler/SkuSelector component. This
component is of class atg.projects.store.assembler.cartridge.handler.SkuSelectorHandler,
which is a class included in the SearchAndNavigation plugin out of the box. The component itself, however,
must be configured in the application module. The configuration included in the B2CStore module is shown
below:
$class=atg.projects.store.assembler.cartridge.handler.SkuSelectorHandler$description=Store-specific version of the product details handler.$scope=prototype
# Import properties.$basedOn=/atg/endeca/assembler/cartridge/handler/ProductDetails
# Instance of SKU Picker Property Manager.skuPickerPropertyManager=/atg/commerce/product/detail/SkuPickerPropertyManager
# Instance of SkuPickers which contains the service map that holds the# different sku pickers that are available.skuPickers=/atg/commerce/product/detail/SkuPickers
# Remove any configured Content Item Modifiers.contentItemModifiers^=/Constants.NULL
The SkuSelectorHandler class is an extension of the
atg.projects.store.assembler.cartridge.handler.ProductDetailsHandler class. Also, the
SkuSelector component as configured in B2CStore is based on the ProductDetails component and
inherits all of that component’s configuration. The portion of the configuration that the SkuSelector
component overrides is:
• skuPickerPropertyManager:This property maps to a component that provides the property identifiers that
are used when transferring the currently selected options (color, size and woodFinish) between the server
and the client.
• skuPickers:The SkuPickers component to use for choosing the appropriate SKU picker for a request.
• contentItemModifiers: contentItemModifiers are used to apply Bean filters to any repository items
included in the response (for example, products). The SkuSelectorHandler does not return repository
items, therefore keeping the contentItemModifiers property as it is configured in the ProductDetails
component would have no effect. For this reason, this property is set to NULL.
The SkuSelectorHandler component builds the SKU picker data objects and adds them to the
ProductInformation content item list in the content item returned by the server for the product details page.
An example of this data is shown below:
"ProductInformation": [ { "endeca:auditInfo": { "ecr:resourcePath": "/content/Web/Product Detail Pages/Default Product Detail Page", "ecr:innerPath": "mainProductContent[0]/ProductInformation[0]" }, "name": "SKU Selector", "metadata": { "keywords": "silk,dry,suede,buttons,newest,clean,blazer,fall,town,leather,", "description": "Greet fall with our newest suede blazer. Dry clean only.",
12 SearchAndNavigation Plugin 95
"title": "CSA Store - Suede Blazer" }, "@type": "SkuSelector", "skuPickers": [ { "options": [ "Black", "Blue", "Olive" ], "type": "color", "value": null }, { "options": [ "S", "M", "L", "XL", "XXL" ], "helperInformation": { "type": "sizeChart", "contentUrl": "SizeChart.html" }, "type": "size", "value": null } ]},
In the example above, you can see a skuPickers array that has been created for a clothing-sku that has both
color and size options. The skuPickers array contains two objects, each representing a SKU picker, one for
color and one for size. Each SKU picker object contains a list of available options as well as the SKU picker type
and the currently selected value. In this case, the value is set to null because no option has been selected. In
cases where only a single option exists for the picker, the value property is set to that single option.
Also seen in this example is the addition of the size chart information included in the helperInformation
object of the size SKU picker. This portion of the data structure defines that the size chart will only appear for the
size picker.
Configuring Helper Information
Helper information can come in many forms. The example included in the B2CStore is a link to a size
chart for the shopper to reference while choosing clothing products. While the size chart itself is found
in an HTML file, ensuring that it is included for rendering within the correct SKU picker is configured
using the /atg/commerce/product/detail/ProductDetailsPropertyManager component in the
B2CStore.Plugins.SearchAndNavigation module.
$description=Properties component used to define product detail related propertiesallowing the property names to be configured in component property files.
# ResolvingMap keyed by the SKU properties that, if present in a product's child# SKUs, will trigger the inclusion of additional information in the response to# the Product Detail Page. In this case, when there is a size property present# the URL for the size chart will be made available to the modal window.additionalInformationProperties+=\
96 12 SearchAndNavigation Plugin
size^=/atg/commerce/catalog/custom/SizeChart.additionalInformationMap
In this example, the additionalInformationProperties map is populated with an entry for the size
property. This entry maps to the additionalInformationMap property of the /atg/commerce/catalog/
custom/SizeChart component, shown below:
$class=atg.projects.store.product.detail.AdditionalInformationProperty$scope=global$description=Properties component used to define size chart related properties,allowing the property names to be configured in component property files.
# Map containing the information required for including the Size Chart on the# Product Detail Page.additionalInformationMap+=\ type=sizeChart,\ contentUrl=SizeChart.html
The SizeChart component is based on the
atg.projects.store.product.detail.AdditionalInformationProperty class and contains a single
property called additionalInformationMap that has been populated with two entries:
• type: Text string used to identify the size chart. This string can be used as a lookup key to retrieve a locale-
specific label for the size chart hyperlink rendered on the product detail page.
• contentUrl: The path to the HTML file that contains the markup for rendering the additional information.
REST Object Examples
The following examples show what the REST objects look like as requests are being sent to the server and
responses are sent back to the client.
// Object sent to server when Black/S are selected for a Suede Jacket{ "selectedColor": "Black", "selectedSize": "S", "productIdPropertyName": "xprod2504", "type": "clothing-sku"}
// Object containing matching SKU received from server{ "selectedSku": { "showSalePrice": false, "type": "clothing-sku", "repositoryId": "xsku2504_4", "isAvailable": true, "size": "S", "id": "xsku2504_4", "color": "Black", "listPrice": 84, "displayName": "Suede Blazer", "inStock": true }}
13 ShoppingCart Plugin 97
13 ShoppingCart Plugin
This chapter provides an overview of the ShoppingCart plugin, its UI components, and configuration. It
includes the following sections:
Shopping Cart Plugin Overview (page 97)
Shopping Cart Plugin UI Components (page 98)
Invoking the ShoppingCart REST Services (page 99)
ShoppingCart Plugin Configuration (page 99)
Shopping Cart Plugin Overview
The CommerceAccelerator.Plugins.ShoppingCart plugin module provides functionality that allows the
shopper to:
• Navigate to the shopping cart page.
• View the order summary.
• View a list of the items in the cart.
• Add items to and remove items from the cart.
• Update item quantities.
• Proceed to check out.
The ShoppingCart plugin also notifies the shopper when:
• Items are added to the cart.
• Cart items are unavailable.
Note: The B2CStore application module includes the
CommerceAccelerator.Applications.B2CStore.Plugins.ShoppingCart module to extend the
functionality in the out-of-the-box ShoppingCart plugin with application-specific code and configuration.
98 13 ShoppingCart Plugin
Shopping Cart Plugin UI Components
The view models (JavaScript files) and HTML renderers for the ShoppingCart plugin’s UI components are
defined in the CommerceAccelerator/Plugins/ShoppingCart/src/main/web-app directory. Templates
for associated cartridges are located in CommerceAccelerator/Plugins/ShoppingCart/src/main/
deploy/import/templates. Note that not all UI components have associated cartridges; those that do not are
marked N/A in the Cartridge Type column of the table below.
UI Component Description Cartridge Type
CartEditor Allows the shopper to view and interact with the
shopping cart, including viewing an order summary,
viewing the items in the cart, removing items from the
cart, updating item quantities, getting notified when
cart items are unavailable and proceeding to checkout.
When the cart is not empty, the CartEditor UI
component renders the OrderSummary UI component,
described below, as well as the CouponEditor UI
component that is part of the Promotions plugin
(CommerceAccelerator/Plugins/Promotions/
src/main/web-app/CouponEditor.js). When the
cart is empty, the CartEditor UI component provides
an “empty cart” message and a Continue Shopping
link.
MainContent
CartLink The CartLink UI component provides a UI to indicate
the current status of the shopping cart. CartLink has
two states: expanded and collapsed, with collapsed
being the default. In the collapsed state, CartLink is a
button that indicates, on the button text, the number
of items in the cart. When the shopper clicks this
button, he is taken to the cart page.
In the expanded state, the CartLink UI component
becomes a Bootstrap modal window, in addition to
the button, that displays the order summary and the
list of items in the cart. CartLink is automatically
expanded when an item is successfully added to cart
and is collapsed by closing the modal window.
HeaderAction
OrderSummary The CartEditor UI component uses the
OrderSummary UI component to display the order
summary, including an item subtotal, discounts,
shipping, taxes, and an overall total.
N/A
13 ShoppingCart Plugin 99
Invoking the ShoppingCart REST Services
The ShoppingCart UI components use the cart-services JavaScript module to invoke REST services and
communicate with the server through XHR requests. Specifically, cart-services enables order summary
retrieval, adding items to the cart, and removing items from the cart. The cart-services JavaScript module is
found in CommerceAccelerator/Plugins/ShoppingCart/src/main/web-app.
ShoppingCart Plugin Configuration
Beyond the general steps for including a plugin in an application module, described in Adding an Out-of-
the-Box Plugin to an Application Module (page 21), there is no additional configuration required for the
ShoppingCart plugin.
100 13 ShoppingCart Plugin
14 Spotlights Plugin 101
14 Spotlights Plugin
This chapter provides an overview of the Spotlights plugin, its UI components, and configuration. It includes the
following sections:
Spotlights Plugin Overview (page 101)
Spotlights Plugin UI Components (page 101)
Spotlights Plugin Configuration (page 102)
Spotlights Plugin Overview
The CommerceAccelerator.Plugins.Spotlights plugin module provides scrollable spotlight carousels that
allow the customer to:
• Scroll through a list of customer-targeted media content items.
• Scroll through a list of customer-targeted products.
While both spotlight carousels can be included in the main content section of any page, they are primarily
designed for use on the home page.
Note: The B2CStore application module includes the
CommerceAccelerator.Applications.B2CStore.Plugins.Spotlights module to extend the
functionality in the out-of-the-box Spotlights plugin with application-specific code and configuration.
Spotlights Plugin UI Components
The view models (JavaScript files) and HTML renderers for the Spotlights plugin module’s UI components
are defined in the CommerceAccelerator/Plugins/Spotlights/src/main/web-app directory. Templates
for associated cartridges are located in CommerceAccelerator/Plugins/Spotlights/src/main/deploy/
import/templates. The following table describes each of the Spotlights UI components.
102 14 Spotlights Plugin
UI Component Description Cartridge Type
ScrollableMediaContentSpotlight-
ATGSlot
Displays the current customer’s targeted
media content items in a carousel widget. The
widget allows the customer to scroll through
the items from left to right and back again.
The customer can also click an item to go to
the page associated with the item’s linkUrl
property.
MainContent
ScrollableProductSpotlight-
ATGSlot
Displays the current customer’s targeted
products in a carousel widget. The widget
allows the customer to scroll through the
products from left to right and back again. The
customer can also click a product to go to the
product’s detail page.
MainContent
Spotlights Plugin Configuration
This section describes required and optional configuration for application modules that use the Spotlights
plugin.
Required Application-specific Configuration for the Spotlights Plugin
The ScrollableMediaContentSpotlight-ATGSlot and ScrollableProductSpotlight-ATGSlot
cartridges both refer to an ATG slot. In order for these cartridges to work, you must define the ATG
slots, as well as the targeters that populate the slots and the scenarios that link them together, and
provide the path to the slots when you add the ScrollableMediaContentSpotlight-ATGSlot and
ScrollableProductSpotlight-ATGSlot cartridge to a page in Experience Manager. See the Personalization
Programming Guide and Personalization Guide for Business Users for detailed information on creating slots,
targeters, and scenarios.
Optional Application-specific Configuration for the Spotlights Plugin
For both the ScrollableMediaContentSpotlight-ATGSlot and ScrollableProductSpotlight-
ATGSlot cartridges, you can choose to configure an application-specific missing image URL. For the
ScrollableMediaContentSpotlight-ATGSlot cartridge, you can also choose to substitute a custom HTML
template that renders application-specific properties.
Adding a Missing Image URL
The ScrollableMediaContentSpotlight-ATGSlot and ScrollableProductSpotlight-ATGSlot
view models include a missingImagePath property. This property defines the URL for the image to render
when the image for a carousel itemis missing. In order to add an application-specific missing image to the
missingImagePath property, you must override the ScrollableMediaContentSpotlight-ATGSlot
ScrollableMediaContentSpotlight-ATGSlot and ScrollableProductSpotlight-ATGSlot
configuration in the application layer according to the instructions provided below.
14 Spotlights Plugin 103
1. Create a CommerceAccelerator/Applications/application/Plugins/Spotlights/src/main/
web-app/ScrollableMediaContentSpotlight-ATGSlot.js file with the following content, replacing
application with the name of your custom application and missing-image-path with the path to the
missing image file.
define([
'CSA.Plugins.Spotlights/ScrollableMediaContentSpotlight-ATGSlot',
'text!CSA.Applications.application.Plugins.Spotlights/
ScrollableMediaContentSpotlight-ATGSlot.html'
], function (oldScrollableMediaContentSpotlightATGSlotMixin, newTemplate)
{
'use strict';
return function scrollableMediaContentSpotlightATGSlotMixin
(vm, element) {
// Decorate viewModel (vm) with the (base) contentItem mixin
oldScrollableMediaContentSpotlightATGSlotMixin(vm, element);
vm.template = newTemplate;
vm.missingImagePath(
'missing-image-path');
return vm;
};
});
Note that, in the code above, the mixin from the original view model, CSA.Plugins.Spotlights/
ScrollableMediaContentSpotlight-ATGSlot, is loaded so that the view model can be decorated
with the original mixin decorations before the property values are overridden. Also, in order to handle
rendering application-specific properties, a new HTML template is being used in the application layer. This
new template is loaded and by overriding the template property it is set as the template to use.
2. Create a CommerceAccelerator/Applications/application/Plugins/Spotlights/src/main/web-
app/ScrollableProductSpotlight-ATGSlot.js file with the following content, replacing application
with the name of your custom application and missing-image-path with the path to the missing image
file.
define([
'CSA.Plugins.Spotlights/ScrollableProductSpotlight-ATGSlot',
'text!CSA.Applications.application.Plugins.Spotlights/
ScrollableProductSpotlight-ATGSlot.html'
], function (oldScrollableProductSpotlightATGSlotMixin, newTemplate) {
'use strict';
return function scrollableProductSpotlightATGSlotMixin (vm, element) {
// Decorate viewModel (vm) with the (base) contentItem mixin
oldScrollableProductSpotlightATGSlotMixin(vm, element);
vm.template = newTemplate;
vm.missingImagePath(
'missing-image-path');
return vm;
};
});
3. Add new ScrollableMediaContentSpotlight-ATGSlot and ScrollableProductSpotlight-ATGSlot
mappings to CommerceAccelerator/Applications/application/Plugins/Spotlights/src/
main/web-app/main.js. Replace application in the code sample below with the name of your custom
application.
104 14 Spotlights Plugin
// Define local configurations
require.config({
paths: {
'CSA.Applications.application.Plugins.Spotlights/
ScrollableProductSpotlight-ATGSlot':
'bower_components/CSA.Applications.application.Plugins.Spotlights/
ScrollableProductSpotlight-ATGSlot',
'CSA.Applications.application.Plugins.Spotlights/
ScrollableMediaContentSpotlight-ATGSlot':
'bower_components/CSA.Applications.application.Plugins.Spotlights/
ScrollableMediaContentSpotlight-ATGSlot',
},
map: {
'*': {
'ScrollableProductSpotlight-ATGSlot':
'CSA.Applications.application.Plugins.Spotlights/
ScrollableProductSpotlight-ATGSlot',
'ScrollableMediaContentSpotlight-ATGSlot':
'CSA.Applications.application.Plugins.Spotlights/
ScrollableMediaContentSpotlight-ATGSlot',}
}
});
4. Create a bower dependency to CSA.Plugins.Spotlights, shown in the "dependencies" code block
below, in CommerceAccelerator/Applications/application/Plugins/Spotlights/src/main/
web-app/bower.json.
{
"name": "CSA.Applications.application.Plugins.Spotlights",
"version": "1.0.0",
"ignore": [
"bower_components"
],
"dependencies": {
"CSA.Plugins.Spotlights":
"../../../../../Plugins/Spotlights/src/main/web-app"
},
"devDependencies": {
"es5-shim": "3.4.0",
"jasmine": "1.3.1"
}
}
5. Edit the CSA.Plugins.Spotlights/main reference in CommerceAccelerator/
Applications/application/src/main/web-app/main.js to use a reference to
application.Plugins.Spotlights/main. Replace application with the name of your custom
application.
define([
// Load package dependency configurations
…
'bower_components/CSA.Applications.application.Plugins.Spotlights/main'
], function () {
'use strict';
14 Spotlights Plugin 105
Replacing the HTML Template for Media Content Spotlights
Applications that need to display application-specific properties for media contentspotlight items must
replace the HTML template for the ScrollableMediaContentSpotlight-ATGSlot cartridge in the
application layer. To do so, copy the CommerceAccelerator/Plugins/Spotlights/src/main/web-
app/ScrollableMediaContentSpotlight-ATGSlot.html file to your CommerceAccelerator/
Applications/application/src/main/web-app directory, then modify the carousel-inner div element
to accommodate your application’s requirements.
106 14 Spotlights Plugin
15 Acronym Definitions 107
15 Acronym Definitions
This appendix defines the acronyms that are used in the Commerce Store Accelerator documentation.
CIM: Configuration & Installation Manager. An Oracle Commerce tool used to configure, assemble, and deploy
Oracle Commerce server instances to an application server.
EAC: Endeca Application Controller. Controls, manages, and monitors components in your Guided Search
implementation. It is installed with the Platform Services package.
SEO: Search engine optimization. Optimizing a web site so that it appears higher in a search engine’s results list,
thereby increasing the likelihood that users will see it.
REST: Representation State Transfer services, also called Web Services. A widely supported standard for
packaging remote procedure calls in an XML-based structure. The Dynamo Application Framework includes
tools that allow you to create custom Web Services that call methods on Nucleus components. These custom
Web Services can expose methods on existing Oracle Commerce Platform Nucleus components, or on Nucleus
components you write yourself. You can call these Web Services from an external application client, thereby
allowing a client to communicate with a server to retrieve and manage data.
108 15 Acronym Definitions