This post walks through adding filtering to the System Configuration page in the CM Client helping you track down a setting as quickly as possible.

We added the Settings Framework in Elastic Path Commerce 6.1 and it's proved incredibly useful in centralizing configuration and easing customization versus the previous XML based approach.  The number of settings out-of-the-box continues to grow plus any additional ones that customers are free to add.  So this tip will show you how to reign in that growing number of settings.

Here's a screenshot of what we'll be producing, if you've spent any time in the System Configuration (like our trusty QA guys) this will be a real time saver.

Changing the layout

I had to refresh my SWT widget layout knowledge a little and found this great page: http://www.eclipse.org/articles/article.php?file=Article-Understanding-Layouts/index.html.  With that excellent refresher I decided I would need a three column GridLayout: a column each for the Edit button, filter label and the filter text widget.  The table would then span all three columns.

First, simply change the number of columns on the SettingDefinitionComposite:

private void setupLayout() {
     final int columns = 3;
     this.setLayout(new GridLayout(columns, false));
}

Then add in a horizontal span to the table's LayoutData - this makes it span the three columns we just created.

final int horizontalSpan = 3;
table.setLayoutData(new GridData(GridData.FILL, GridData.FILL, true, true, horizontalSpan, 1));

Note: the final variables are to keep Checkstyle quiet about magic numbers.

Adding the new widgets

The code below adds the label and the filter Text widget.  Take a close look at the style we are using to create the Text widget with: SWT.SEARCH | SWT.CANCEL.  The SWT.SEARCH style gives us the rounded edges (at least on my Mac) which makes it look like a regular search/filter widget.  The SWT.CANCEL style adds the small cross to the widget.  When clicked it removes the currently entered text.

Label label = formToolkit.createLabel(this, AdminConfigurationMessages.filterLabel + ":"); //$NON-NLS-1$
GridData gridData = new GridData(SWT.END, SWT.CENTER, false, false);
label.setLayoutData(gridData);
Text settingNameFilter = formToolkit.createText(this, "", SWT.SEARCH | SWT.CANCEL); //$NON-NLS-1$
gridData = new GridData(SWT.FILL, SWT.CENTER, false, false);
final int verticalIndent = 10;
gridData.verticalIndent = verticalIndent;
settingNameFilter.setLayoutData(gridData);

We want this new addition to be localizable so we need to add AdminConfigurationMessages.filterLabel

public static String filterLabel;

And then we provide the English version of that in AdminConfigurationPluginResources.properties

filterLabel=Filter

Filtering

Now we'll take a look at how we will actually filter down the table's contents.  The code's pretty simple:

/**
 * Filter setting definitions against a specified string.
 */
private class SettingPathFilter extends ViewerFilter {
     private final String filterText;
     public SettingPathFilter(final String filterText) {
          this.filterText = filterText;
     }
     @Override
     public boolean select(final Viewer viewer, final Object parent, final Object element) {
          SettingDefinition definition = (SettingDefinition) element;
          return StringUtils.containsIgnoreCase(definition.getPath(), filterText);
     }
}

We've simply extended the JFace ViewerFilter class and implemented the select method with a case-insensitive check against the setting definition's path.  In the next step we'll create an instance of this class and pass it to the TableViewer that holds the setting definitions.

The following page helped me a bit with the ViewerFilter: http://www.java2s.com/Code/Java/SWT-JFace-Eclipse/DemonstratesListViewer.htm

Hooking it together

The bits are all in place, let's tie them together and get the filtering going when a user types in the text box.  We simply add a ModifyListener to the filter Text widget and when we receive a ModifyEvent we grab the user-entered string, create a new SettingPathFilter and set that on the tableViewer.  That triggers the tableViewer to filter its contents.  Note: I chose to use setFilters, rather than addFilter/removeFilter, to keep the code simple: I don't have to keep track of the filter to remove it afterwards I simply call setFilters again.

settingNameFilter.addModifyListener(new ModifyListener() {
     public void modifyText(final ModifyEvent event) {
          final Text source = (Text) event.getSource();
          String filterText = source.getText();
          if (StringUtils.isBlank(filterText)) {
               tableViewer.setFilters(new ViewerFilter [0]);
          } else {
               tableViewer.setFilters(new ViewerFilter [] {new SettingPathFilter(filterText)});
               }
     }
});

Conclusion

So there you have it, all done, with a few small changes we can find settings without having to visually scan the table.  Where else might this filtering function be useful?  Anyone done any similar customizations they would like to share?

The code

The code changes and the attached patch are against the upcoming 6.2 release, but I'm pretty sure they will apply to any 6.1+ version.  Leave a comment if you have any problems applying this and I'll do my best to help you out.

References

http://www.eclipse.org/swt/snippets/ - if you've not taken a look at the SWT snippets then you're missing out.  There's a ton of useful examples of using SWT.

http://wiki.eclipse.org/index.php/JFaceSnippets - just like the SWT snippets, this page contains great snippets about using the JFace ui toolkit.

Why Upgrade?

The Upgrade

The following diagram shows the branches referred to in the svn merge command and our desired "Customized EP 6.1" end state:

When svn merge hits a conflicted file, it produces 3 output files. For example, consider a file called MyClass.java that is conflicted; svn merge will produce the files MyClass.java.left, MyClass.java.right, and MyClass.java.working. The highlighted colors correspond to the branches in the svn merge command above. The .left file is the EP6.0 version, the .right file is the EP 6.1 version, and the .working file is our customized codebase version.

INSERT INTO TSETTINGDEFINITION(UIDPK, PATH, DEFAULT_VALUE, VALUE_TYPE, DESCRIPTION, MAX_OVERRIDE_VALUES)
 VALUES(81, "CUSTOM/tradeshowTimeout", "120000", "Integer", "Indicates the tradeshow timeout interval, in seconds.", -1);

timeoutId = window.setTimeout("resetTradeshowPage()", $ctxStoreConfig.getSetting("CUSTOM/STORE/tradeshowTimeout").getValue());

final String settingValue = getSettingsService().getSettingValue("CUSTOM/STORE/tradeshowTimeout").getValue();
 

<dependency>
    <groupId>maxmind</groupId>
    <artifactId>geoip</artifactId>
    <version>1.2.1</version>
    <scope>compile</scope>
</dependency>

<repository>
    <id>ps-extras</id>
    <name>Elastic Path PS Extras Repository</name>
    <url>http://maven-ps.elasticpath.net:8080/archiva/repository/extras/</url>
    <releases>
        <enabled>true</enabled>
    </releases>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

Testing & Bug Fixing

Time Estimates

Conclusion

Many classes were refactored in Elastic Path 6.1 to improve testability of existing code and to accommodate new features (most notably the ability for a single Storefront WAR file to host multiple Stores). Here are the changes with the highest impact for developers (in no particular order).

1. Refactoring of ElasticPathImpl.java and Creation of the Settings Framework

ElasticPathImpl covers several distinct areas of responsibility: BeanFactory, Configuration, Filtered Navigation, asset lookup... In 6.1, new interfaces were created to move those areas of functionality out of ElasticPathImpl with the intention of rendering the object obsolete in future versions.

• Most configuration settings are now accessed via the SettingsService, which will be covered in a separate article. Commerce-config.xml files are no longer used to populate a map of settings in ElasticPathImpl, with the exception of the one in the CM web application, which is only used to keep track of the EP version and build number
• Asset locations are now retrieved from the AssetRepository interface (see heading elsewhere in this article)
• Search Configuration is now retrieved entirely from the Settings framework rather than from the ElasticPath object
• Filtered Navigation information is still retrieved from ElasticPathImpl, but only because it implements the new FilteredNavigationConfiguration interface. The actual retrieval implementation now lives in a separate class and references the new Settings framework
• Bean instances can still be retrieved from ElasticPath because ElasticPathImpl implements the BeanFactory interface, but from this point onward the ElasticPath object is not required to be injected into classes that only need a BeanFactory. Instead, you should inject an implementation of BeanFactory

If any customizations were performed on some Elastic Path 6.0 code base that must be transferred to an Elastic Path 6.1 code base, most careful attention should be paid to any changes in the ElasticPath singleton, especially if any new settings were introduced that are designed to be read in from a commerce-config.xml configuration file. Since most settings were moved to the Settings framework, the code to parse the configuration file has mostly been removed.

New customizations should pay special attention to the Settings framework and use it where appropriate. Also, the BeanFactory should be injected into new classes where required instead of the ElasticPath object, as its use as a bean factory is being phased out.

New persistent classes should have a DAO that is separate from any new services, to allow for more flexible persistence implementations if functionality changes.

2. Testing Framework Enhancements

In testing, the big news is deprecation of ElasticPathTestCase.java and the introduction of JUnit4 and JMock2 testing frameworks.

Prior to 6.1, many test classes extended ElasticPathTestCase.java, which is a JUnit 3.8 extended test class that mocks out much of the application's domain using mock objects created with the JMock 1.x framework. This class is being phased out, and use of it is no longer recommended because it:

• is large and unwieldy
• encourages poor code factoring and integration tests using mock objects
• is complex; modification may affect many test cases in an unforeseen manner

Instead, unit test classes should focus on unit-testing rather than integration-testing methods. Use of the JUnit4 and JMock2 framework features should help in that regard. There are many examples of their use in the new code; but for a start you may want to look at GiftCertificateThemeImplTest (for a relatively simple test class) and StoreResourceManagerImplTest (which takes advantage of some advanced features in the new JMock framework).

3. New Store UI Themes and Asset Retrieval

Store-specific Velocity template resolution has been introduced. Most static and storefront theme content (storefront velocity templates, email velocity templates, javascript files, css files, Power Reviews, etc) was moved outside the separate application WAR files into the pre-existing Assets folder on the file system.

In 6.0 only some assets (store images and digital goods) lived on the file system under the assets folder, while others (email templates, storefront UI files, and PowerReviews files) lived inside the WAR. All of these files were moved to appropriate locations under the file system's assets folder and the paths to such folders were made available through an AssetRepository object rather than through methods on the ElasticPath object. This allows the assets to be modified at runtime.

The Storefront application's Themes feature (see Themes documentation) required the introduction of a StoreResourceManager to handle Velocity's lookups and caching for Storefront velocity templates. It does not use the AssetRepository, but instead uses very similar code combined with hardcoding the velocity template directory within the assets folders (see StoreVelocityConfigHelper.java). A separate Velocity Engine is created for each and every Storefront operating within a WAR.

The Storefront's asset requests that are not for Velocity templates (e.g. css, javascript, images, Power Reviews) go through the AssetResourceController, which uses the AssetRepository indirectly through an AssetRetrievalStrategy. In order for controllers to know which store they are working with, a ThreadLocal reference to Store has been introduced, set by the StoreSelectionFilter. Any storefront controller requiring parameters specific to the store that is accessing the controller can inject the StoreConfig object, or they can retrieve it from the RequestHelper, which also has it injected. The current store is no longer retrieved from ElasticPath.java.

4. New DAO classes

New DAO classes were introduced in some areas to separate service logic from persistence operations. In addition to some new features using separate Service and DAO classes, existing Services which have had DAO functionality factored out include:

• ProductService / ProductDao
• ProductTypeService / ProductTypeDao

DAO classes should generally not be accessed directly from outside of the Service layer. Such separation of business logic and persistence logic allows for far more flexibility and decoupling in the application. Future development should endeavor to follow this pattern (See the GiftCertificateThemeService / GiftCertificateThemeStoreAssignmentDao for an example of how such decoupling can be of benefit).

5. Index UID / GUID fields

We are phasing out UID fields in the indexes, in favor of GUID fields, for greater decoupling. Secondary object UID fields have, for the most part, been replaced with GUID fields in object indexes so that searches can be performed based on GUIDs. For instance, the CategoryIndex contains the CategoryUid so that the UID can be retrieved from the index when a search match is found, but the index is built using the GUIDs from associated objects (e.g. you can search the CategoryIndex to return categories that are associated with a particular CatalogCode, but not with a particular CatalogUid). The corresponding SearchCriteria objects have been modified to reflect the index schema changes.

Index fields that have been modified as a result of this change are as follows:

• CategoryIndex:

• PromotionIndex

• ProductIndex

In addition, several fields were added to the OrderReturn index schema.

6. Improved Index Build Status Tracking

The status of indexes, and the method of causing them to rebuild, has changed drastically:

• The index build status (including the last time the index was built) is stored in the new TINDEXBUILDSTATUS database table, and can be accessed using the IndexBuildStatusService.
• On the Search Server, the AbstractIndexServiceImpl class manipulates the status of index builds directly through the IndexBuildStatusDao.
• The Commerce Manager Client has a new View that enables index rebuilds to be triggered manually.

In addition, if the server is brought down (either manually or catastrophically) while in the process of building an index, it will now remember its status upon restart and will start a new rebuild rather than assuming that the index is complete.

7. New Store Editor GUI

The Store Editor has been enhanced to better handle store themes. In addition, it has abstracted most of the business logic from where it may previously have been embedded in the UI code.

You can run queries immediately using the CM client's UI. This is convenient for testing, but it doesn't allow you to schedule actions on the query results. Let's say you want to perform a daily action on products that match the criteria in the previous example. To do that, you would need to create a class that retrieves the products using EPQL and sends that information to a third party system for processing.

To use the EPQL search APIs, you need to add com.elasticpath.core.jar and com.elasticpath.ql.jar file to your project's classpath.

Next, add the required Spring bean definitions. Create a file named serviceEPQL.xml in the project's conf/spring/service folder and add a reference to it from the Spring application-context.xml. For an example, take a look at the com.elasticpath.cmclient.core RCP plugin or the import/export tool.

Create a Java class that will be used to retrieve the products using EPQL. The following code shows how to execute an EPQL query:

The EpQLSearchEngine class has a search method that executes a query and returns the results. Before executing a query, you should make sure that it is syntactically valid.

The EPQLQueryParser class provides a verify method that takes a query string as an argument. If there's an error in the query, it throws an exception, including a detailed description to help you fix the problem.  The search result set contains the list of UIDs of the objects that matched the query.

Elastic Path Commerce 6.1 introduces a number of changes from version 6.0.x. Primary among these are a major change to the store asset directory structure; movement of store configuration information from the file system to the database; and a number of minor changes to the existing database tables. As a result, 6.0.4 deployments with existing data can be upgraded to the 6.1 codebase with relocation of store assets; migration of configuration files into the database; and database upgrade scripts.

Note that it's assumed that the codebase has already been upgraded to 6.1; it's up to you to decide how code merge is done. It's also assumed that the existing deployment was already at the latest service release (6.0.4) before upgrading to 6.1.

Store Assets Relocation

Along with the XML configuration files, store-specific visual presentation elements used in the Storefront and emails have been moved from the WAR files into a central assets directory.  These include all Velocity templates, message properties files, images, javascript, css and Power Reviews.

• The simplest way to move storefront assets out of the WAR file is to copy the directories com.elasticpath.sf/template-resources and com.elasticpath.sf/WEB-INF/templates to the new assets directory under a theme folder of your choosing. The assets directory will have the structure:

assets/themes/<theme_name>/<store_code>/templates

assets/themes/<theme_name>/<store_code>/template-resources

• Email templates previously located in com.elasticpath.cm/WEB-INF/templates also need to be moved to the assets folder. Email templates and property files that are not connected to any particular store will need to be moved to: assets/cmassets/templates/velocity

• Storefront related emails will be located under their respective theme folders: assets/themes/<theme_name>/<store_code>/templates/velocity

Configuration File Migration

Much of the configuration data previously in XML files within Elastic Path WAR directories has been moved into the database to be managed through the Settings framework in the CM. This includes commerce-config.xml, search-config.xml, urlrewrite.xml, intelligent-browsing.xml. Please consult the settings framework documentation before migrating configuration settings.

• With the exception of web.sf.context.url, all settings previously in commerce-config.xml have been moved to the Settings framework and are no longer required to be in the XML file. Values in these settings (e.g. VFS paths/login) should be updated in the Settings framework through the CM Settings configuration view as new Setting values or inserted into tables TSETTINGVALUE where appropriate. Additional custom settings in commerce-config.xml file should be moved to the Settings framework as new Setting definitions in TSETTINGDEFINITION. A table of where settings in the commerce-config.xml reside in the settings framework is provided in Appendix A.

• Content in intelligent-browsing.xml has been moved to the Settings framework and the file is no longer needed. Its contents should be inserted as a new Setting Value for the setting COMMERCE/STORE/FILTEREDNAVIGATION/filteredNavigationConfiguration

The content can also be copied into the CM Store Editor's Filtered Navigation section.

• Content in urlrewrite.xml has been moved to the Settings framework and the file is no longer needed. Its contents should be inserted as a new Setting Value for the setting COMMERCE/SYSTEM/urlRewriteConfig

• Content in search-config.xml has been moved to the Settings framework and the file is no longer needed. If any customization has been made, the Setting values under the paths COMMERCE/SEARCH/<setting> should be updated appropriately.

Database Upgrade

Upgrade SQL scripts are provided along with each release of Elastic Path to capture changes in the database schema between the new release and the latest service release.

Each supported database (MySQL, SQL Server, Oracle) will have its own upgrade script.

• Upgrade scripts are provided in the 6.1 distribution for each database, and should be run by the tools provided by the database vendor.
• Upgrade scripts will apply schema changes and insert necessary base data on an existing 6.0.x database, but does not change existing data.

After running the upgrade script, the steps can be done through the CM or directly through the database to get your deployment up and running:

• Reassign supported currency and supported locales to existing stores in the CM, or insert entries in the TSTORESUPPORTEDCURRENCY and TSTORESUPPORTEDLOCALE respectively.
• Change the display theme of existing stores appropriately by editing the COMMERCE/STORE/theme setting in either the System Configuration section of the CM or the Store Editor.
• Set the correct value for the search server in the settings framework, under the path COMMERCE/SERVER/SEARCH/searchHost
• Search indexes need to be rebuilt. This is an automatic step if old indexes are deleted.
• Set the correct values for the asset VFS in the settings framework under COMMERCE/APPSPECIFIC/RCP/ASSETS/<setting>
• Gift certificate themes need to be recreated through the CM, and assigned to stores in the CM Store Editor.
• Be aware that stores can now only be accessed through the URL defined in the CM Store Editor (TSTORE table in the databse), and care should be taken when testing.

Caveats

• The upgrade process cannot cover all possible database and code customizations to the 6.0.x codebase, and upgrade scripts should be reviewed before running on any schemas that you have customized.
• Before moving existing storefront assets, be aware that there are changes in these files (Velocity templates, property files) that might not be picked up through a normal code merge due to the change in location.
• New configuration settings introduced in 6.1 take on their default values after an upgrade, and should be reviewed for correctness.

Upgrading to 6.1 from 6.0.4 requires little database change. Configuration files and asset migration make up the bulk of the upgrading effort, and existing customizations to configuration and assets should be reviewed to take advantage of the new settings framework and asset repository.

Asset management has changed significantly in EP 6.1 to make deployment of multiple stores easier. With EP 6.1, multiple stores may be run in a single WAR file, hence there is no need to copy WAR instances to deploy a new store. Asset types, which include images, CSS, JavaScript, email templates, storefront velocity templates, VM_global_libraries and Message Resource property files, have been moved out of the WAR deployment location and into a new directory elsewhere on the file system. The previous structure of the assets directory has also changed.

The assets root directory structure is as follows:

- assets

+ cmassets

+ digitalassets

+ images

+ import

+ storeassets

+ themes

The absolute path for assets is specified in your deployment's COMMERCE/SYSTEM/ASSETS/assetLocation setting. EP6.1 also introduces the "Settings Framework," a new component that contains system and store configuration settings that used to be captured in commerce-config.xml and other files. The COMMERCE/SYSTEM/ASSETS/assetLocation setting value must be configured before you start your storefront application to point at your assets root directory, for example c:\assets or /opt/assets.

• The cmassets directory is also new in EP 6.1 and contains the Commerce Manager specific files, such as user account email templates and the import report email template.
• The digitalassets directory has been around for several releases and still contains the downloadable digital product files.
• The images directory is also not new and contains your product display images.
• The import directory was introduced in EP 6.0 and contains all import CSV files used by the Commerce Manager. Please note that these files are not used by the Import/Export tool, which is a separate component.
• The storeassets directory is new in EP 6.1 and only contains the PowerReviews required by each store. This directory is specific to each store, but does not form part of a theme.
• The themes directory is new and serves as the root directory for all themes used by your stores. Themes are used to define the look and feel of stores in EP. You can create multiple themes and associate these with one or more stores. You can also customize theme elements (images, CSS, JavaScript) for individual stores without affecting other stores that use the same theme.

A theme consists of a set of Velocity templates and resources required to display a storefront (stylesheets, images, properties files, etc.). Each theme is stored in its own directory under the assets/themes directory:

- assets

+ cmassets

+ digitalassets

+ images

+ import

+ storeassets

- themes

  + electronics

  + mytheme1

  + mytheme2

  + ...

Each theme must contain a default directory. This directory contains the templates and the template-resources directories. The templates directory contains the Velocity templates used by the Velocity Engine to render HTML pages. The template-resources directory contains the stylesheets, Javascript and image files referred to by the rendered HTML pages.

- assets

+ cmassets

+ digitalassets

+ images

+ import

+ storeassets

- themes

  - electronics

    - default

      - template-resources

        + images

        + js

        + stylesheet

      - templates

        - velocity

          + index.vm

Within these directories, you can use any directory structure you want to organize files, but keep in mind the file-based fallback mechanism used within themes.

Themes can be customized to suit the needs of individual stores. To customize a theme for a specific store, create a directory under the theme and set the directory name to the store code. For example, to customize mytheme1 for the SNAPITUP store, create a directory named SNAPITUP under mytheme1. The directory structure should look similar to the following:

- assets

+ themes

- mytheme1

  + default

  + SNAPITUP

In the store-specific directory, only create copies of the files that you want to customize. The copies must exist in the same relative directory structure within the store-specific directory. For example, to customize the mytheme1/default/template-resources/images/image-not-available.png image for the SNAPITUP store, place the custom version of image-not-available.png in mytheme1/SNAPITUP/template-resources/images.

- assets

- themes

  - mytheme1

    - default

      - template-resources

        - images

          + image-not-available.png (default image)

          + ... all other shared images

    - SNAPITUP

      - template-resources

        - images

          + image-not-available.png (store overriding image)

It is not necessary to copy the entire contents of the default directory into the store-specific directory. You only need to include copies of the files that you are customizing. The application looks for files in the store-specific directory first; if it does not find a file in the store-specific directory, it then looks for it in the default directory. In other words, your customized copy of the file or image acts as an override for the default file or image. This file-based overriding mechanism is used for images, stylesheet, JavaScript and Velocity template files.  Access to these resources is handled by resource controllers, which in turn use resource retrieval strategies for greater flexibility.

WEB-INF/conf/spring/web/url-mapping.xml

<bean id="SimpleUrlHandlerMapping"

    class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">

  <property name="mappings">

      <props>

      <prop key="/images/**/*">storeThemeAssetResourceController</prop>

      <prop key="/stylesheet/**/*">storeThemeAssetResourceController</prop>

      <prop key="/js/**/*">storeThemeAssetResourceController</prop>

      </props>

  </property>

</bean>

<!-- Resource controllers for resource retrieval -->

<bean id="storeThemeAssetResourceController"

    class="com.elasticpath.sfweb.controller.impl.AssetResourceControllerImpl"

    parent="abstractEpController">

  <property name="resourceRetrievalStrategy"

            ref="storeThemeAssetRetrievalStrategy"/>

</bean>

Message Sources use a property based overriding mechanism, as opposed to the file based overriding for other types of assets like images. Message Sources are a collection of property files, which associate message keys to message text in different languages. Take, for example, the globals.firstname property key that's located in 2 files, one referencing the English message and the other the French message.

- assets

- themes

  - mytheme1

    - default

      - templates

        + globals.properties  : globals.firstname=First Name

        + globals_fr.properties: globals.firstname=Prenom

To override the French globals.firstname message for the SNAPITUPUK store, one need only override one property, not the entire property file. In this case the global_fr.properties file need only contain a single property entry for globals.firstname.

- assets

- themes

  - mytheme1

    - default

    - templates

        + globals_fr.properties: globals.firstname=Prenom (default)

    - SNAPITUP

      - templates

        + globals_fr.properties: globals.firstname=Prénom (overriding)

In fact, the file name need not even start with "globals" as all properties are loaded into a collection at which point file names are no longer relevant. The only requirement is that it contain the language code. For example, having the globals.firstname property override in a file named no-name-in-particular_fr.properties, will have the same effect. If no language code is present, English is assumed.  For reference, see the Message Source configuration in the Storefront and Commerce Manager web applications.

WEB-INF/conf/spring/views/velocity/velocity.xml

<bean id="messageSource"

    class="com.elasticpath.commons.util.impl.StoreThemeMessageSource" >

  <property name="messageSourceCache">

      <ref bean="messageSourceCache"/>

  </property>

  <property name="storeConfig">

      <ref bean="threadLocalStorage"/>

  </property>

  <property name="globalMessageSource">

      <ref bean="globalMessageSource"/>

  </property>

  <!-- True if you want missing messages to show up

        as just the key used to look for them. e.g. user.firstname.

        False will allow exception to be thrown, and stop template render.

  -->

  <property name="useCodeAsDefaultMessage">

      <value>true</value>

  </property>

</bean>

Using Store Editor

You can select the theme using the new store editor:

1.  In Commerce Manager, choose *Activity*->*Configuration*.

2.  Under *Stores*, click *Stores*.

3.  Select the store, then click *Edit Store*.

4.  Click the *Theme* tab.

5.  In the _Theme_ box, enter the name of the theme folder. For example, if the theme folder is C:/Program Files/Apache Software Foundation/apache-tomcat-5.5.26/assets/themes/mytheme1, enter mytheme1.

6.  In the Commerce Manager toolbar, click *Save*.

Using Advanced Setting Configuration

By default, the demo store is mapped to the electronics theme. To change the theme of a store:

1.  In Commerce Manager, choose Activity -> Configuration.

2.  Under System Administration, click System Configuration.

3.  In the Property Name list, select COMMERCE/STORE/theme.

4.  Click New (next to the Defined Values list).

5.  Set the values as follows:

·        Context: The store code. For example, for the SnapItUp demo store, the store code is SNAPITUP.

·        Value: The name of the theme folder. For example, if the theme folder is C:/Program Files/Apache Software Foundation/apache-tomcat-5.5.26/assets/themes/mytheme1, enter mytheme1.

6.  Click Save.

During the development of EP 6.1 it was clear that we had to find a way to make the Velocity engine's VM_global_library store specific since stores do not always share the same library macros.  In EP 6.0, Spring instantiated a VelocityEngine bean directly to inject into the onePageHelper bean, as OnePageHelperImpl requires a Velocity engine for some functionality. This bean is also injected into the velocityConfig bean which is what the VelocityView class uses to get the Velocity engine (it is effectively a factory). The VelocityView class retrieves the Velocity engine once, but we want it to get the appropriate store engine each time the view is asked to render a template.

Among other smaller changes, the following classes needed to be added in EP 6.1 to correct the Velocity Engine behavior.

<bean id="viewResolver"

class="com.elasticpath.sfweb.view.velocity.StoreVelocityViewResolver">

  <property name="viewClass">

<value>com.elasticpath.sfweb.view.velocity.StoreVelocityViewImpl</value>

  </property>

  <property name="velocityConfigurer" ref="velocityConfigurer"/>

  ...

</bean>

<bean id="velocityConfigurer"

    class="com.elasticpath.sfweb.view.velocity.StoreVelocityConfigurer">

  <property name="storeConfig" ref="threadLocalStorage"/>

  <property name="velocityPropertiesMap" ref="velocityPropertiesMap"/>

</bean>

StoreVelocityConfigurer

This is a subclass of VelocityConfigurer which keeps a Map of velocity engines keyed by store code. This class just overrides the getVelocityEngine() method and uses an injected store config to retrieve the appropriate VelocityEngine instance from the map. It will call createVelocityEngine() if there is no value for the store currently in the map.

StoreVelocityViewResolver

This is a subclass of VelocityViewResolver which is store aware. It has setters for a StoreConfig and VelocityConfigurer which will typically be injected by Spring. This class overrides the buildView method and passes the store config and velocity configurer through to the StoreVelocityViewImpl class so it can render the store-specific view.  The old "global" WEB-INF/VM_global_library.vm library has been removed. You now have a VM_global_library in the templates/velocity directory of a theme or store-specific theme override. This will fall back exactly like the other assets.

- assets

- themes

  - mytheme1

    - default

      - templates

        - velocity

          + VM_global_library.vm (default fall-back)

    - SNAPITUP

      - templates

        - velocity

            + VM_global_library.vm (store specific override)

Store Specific Report Templates

Report Design files (*.rptdesign) are typically bundled as part of the Commerce Manager plugin. Packing Slip reports are store specific though, and had to be moved out of the plugin and uses the theme to take advantage of the file-based overriding mechanism.

- assets

- themes

  - mytheme1

    - default

      - templates

        - printartifacts

          + packing_slip.rptdesign (default report design)

    - SNAPITUP

      - templates

        - printartifacts

            + packing_slip.rptdesign (store specific override)

The com.elasticpath.cmweb.controller.impl.CacheInvalidationControllerImpl defined in the CM Server is useful to invalidate caches of various types based on an invalidation strategy. The default configuration, as displayed below and duplicated in the Storefront, uses the TriggeredCacheInvalidationStrategy to invalidate the Velocity engines and message resources.

com.elasticpath.cm/WEB-INF/conf/spring/web/url-mapping.xml:

<prop key="/invalidate-cache.ep">cacheInvalidationController</prop>

<bean id="cacheInvalidationController"

    class="com.elasticpath.cmweb.controller.impl.CacheInvalidationControllerImpl">

  <property name="cacheInvalidationStrategy"

            ref="triggeredCacheInvalidationStrategy" />

</bean>

com.elasticpath.cm/WEB-INF/conf/spring/service/serviceCM.xml:

<bean id="triggeredCacheInvalidationStrategy"

class="com.elasticpath.commons.util.impl.TriggeredCacheInvalidationStrategyImpl">

  <property name="invalidatableCaches">

      <bean class="java.util.HashSet">

          <constructor-arg>

              <set>

                  <ref bean="velocityEngineFactory"/>

                  <ref bean="messageSourceCache"/>

              </set>

          </constructor-arg>

      </bean>

  </property>

</bean>

Be sure to have the invalidation URL secured, as it will cause a hit in performance every time the velocity engine is recreated, which reloads all the message property files.

For information on configuring PowerReviews in Elastic Path, see the PowerReviews Wiki page at https://wiki.elasticpath.com/display/EP61DEPLOY/5+-+PowerReviews+(optional) in the Deployment Guide. For information on the Power Reviews system, see the PowerReviews website at http://www.powerreviews.com.  The Power Reviews component is enabled and disabled by the boolean store-specific setting COMMERCE/STORE/POWERREVIEWS/powerreviewsEnabled. The value of the setting is passed to Velocity code by the powerReviewsEnabledHelper Spring bean defined in com.elasticpath.sf/WEB-INF/conf/spring/service/serviceSF.xml. Power Reviews are rendered by JavaScript code, and examples can be found in the guidedSkuTemplate.vm and productTemplate.vm templates.

WEB-INF/conf/spring/web/url-mapping.xml

<bean id="SimpleUrlHandlerMapping"

    class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">

  <property name="mappings">

      <props>

      <prop key="/power-reviews/pwr/engine/js/**/*">

            storeAssetResourceController</prop>

      <prop key="/power-reviews/pwr/engine/**/*">

            storeAssetResourceController</prop>

      <prop key="/power-reviews/pwr/content/**/*">

            storeAssetResourceController</prop>

      </props>

  </property>

</bean>

<!-- Resource controllers for resource retrieval -->

<bean id="storeThemeAssetResourceController"

    class="com.elasticpath.sfweb.controller.impl.AssetResourceControllerImpl"

    parent="abstractEpController">

  <property name="resourceRetrievalStrategy"

            ref="storeThemeAssetRetrievalStrategy"/>

</bean>

<bean id="storeAssetResourceController"

    class="com.elasticpath.sfweb.controller.impl.AssetResourceControllerImpl"

    parent="abstractEpController">

  <property name="resourceRetrievalStrategy"

            ref="storeResourceRetrievalStrategy"/>

</bean>