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
    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 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.

Copyright © 1997, 2016 Oracle and/or its affiliates. All rights reserved. Legal Notices