Merging ATG Self Service with an Existing J2EE Application

You must combine the ATG Self Service application module and your application module into a single J2EE application with a single context-root. These instructions assume that you are using your own module named DSSJ2EEDemoSS with a J2EE application called QuincyFunds.

1.Make a copy of your application module and rename it. For example, DSSJ2EEDemoSS.

Copy the <ATG9dir>/Service9.4/Service/SelfService/config directory into the <ATG9dir>/DSSJ2EEDemoSS/config/directory. Don’t overwrite any files. If there are files that overlap, copy the contents of the .properties file from ATG Service into your application.

2.Repeat the procedure for the liveconfig directory.

3.Copy over the <ATG9dir>/Service9.4/Service/SelfService/
lib/classes.jar file into your <ATG9dir>/DSSJ2EEDemoSS/lib directory. If you already have a lib/classes.jar, rename the classes.jar from SelfService to ssClasses.jar.

4.In the <ATG9dir>/DSSJ2EEDemo/META-INF/MANIFEST.MF file add the following:

ATG-Class-Path: lib/classes.jar (or lib/ssClasses.jar)

If you already have an ATG-Class-Path declaration, add a space after the last entry in that line, and add lib/classes.jar or lib/ssClasses.jar to it.

Make sure there is an ATG-Config-Path: config/ line and an ATG-LiveConfig-Path: liveconfig line in the file as well.

Add PublishingAgent Service.common-ui to the ATG-Required: line.

5.Make an ss directory in your root web-app folder. For example:

<ATG9dir>/DSSJ2EEDemo/j2ee-apps/QuincyFunds/web-app/en/ss

Copy into this new directory everything from the <ATG9dir>/Service9.4/
Service/SelfService/j2ee-apps/selfservice-ear/_SelfService/ directory.

(This is assuming that you have already followed the directions on how to expand the SS ear file into folders from Accessing the Application.)

6.Except for web.xml, move all the files from the <ATG9dir>/DSSJ2EEDemo/j2ee-apps/QuincyFunds/web-app/en/ss/WEB-INF/* directory into the <ATG9dir>/DSSJ2EEDemo/j2ee-apps/QuincyFunds/web-app/WEB-INF/

Important: Do not overwrite files if they have the same name.

7.Delete the <ATG9dir>/DSSJ2EEDemo/j2ee-apps/QuincyFunds/web-app/en/ss/META-INF directory:

8.Change the <ATG9dir>/DSSJ2EEDemo/j2ee-apps/QuincyFunds/web-app/WEB-INF/web.xml file to add the following filter mappings:

<filter-mapping>
    <filter-name>RequireLoginFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>
</filter-mapping>

You can now include ss into your application using the following:

<dsp:include src="ss/main.jsp"></dsp:include>

Adding Custom Panels In ATG Self Service

You can add custom panels to the ATG Self Service user interface.

Before you begin, start your ATG Self Service application.

1.Using the ACC or Eclipse, create a new Web application for the customer who needs the custom panel. The Web application’s context root must be /svc-external.

  Note: This context root is already configured in web.xml so no additional configuration is required to use it.

Everything in a particular panel is implemented in a single JSP. These JSPs can exist in either the Self Service application or any other Web application whose context-root is declared in the Self Service application’s web.xml file. The atg.dynamo.contextPaths attribute lists all of the context-paths this web application knows about. This enables you to include JSPs from other Web applications. The DSP:include src="[pagename]" uses the param values specified in this attribute. By default, all Self Service panels are stored in the /panels directory.

Note: Never put new panels here; use links to external web applications instead.

2.Create your JSP. Include any required taglibs. The basic structure for the content should be:

<div class="panel">
     <div class="panelContent">
      [your content here]
     </div>
</div>

3.Build your Web application.

4.In the BCC, log in as a user that has permission to access the Service Admin Publishing menu.

5.Select Service Admin Publishing > Service Admin to access a deployable project.

6.Name the project and click Continue.

7.On the Assets tab, click Add asset to project.

8.Select Service Repository as the Repository, and select PanelDefinition as the Asset Type. Click Create New.

9.Set the following properties as indicated:

a.appId: selfService

b.contentUrl: /svc-external/pathtoyourJSP

c.panelId: panel_id

  This should be a meaningful and unique value.

d.helpKey: help_id

  This is optional, but you may wish to use it.

e.nameKey: name_key

  Used for rendering the panel in the Admin UI.

f.titleKey: title_key

 Used as the title of the panel in the UI. The helpKey, nameKey, and titleKey are all  references into a resource bundle (which values you will create later in this procedure).

10.Click Apply.

11.Click Back to the Project’s Assets.

12.Click Add Asset to Project. Select ServiceRepository as the Repository, and PanelStackDefinition as the Asset Type.

13.Click Add Existing to bring up the Asset Picker, and locate the panel stack to which you want to add the new panel.

14.Select the panel stack. It must be a Self Service panel stack, and should be targeted to segmentName: Everyone-External.

15.Click Add to add the asset to the project, then click Close. The asset should now appear in your Assets list.

16.Select the new asset. In the list of panelIds, click Add a New Element. Enter the panelId of the panel you are adding. You can move it up or down in the panel stack as necessary. Click Apply.

17.Click Back to the Project’s Assets to return to the Projects page.

18.Select the Tasks tab.

19.In the Actions list, select Check In and Deploy, then click Go. Enter a message if you want in the confirmation dialog, and click OK.

20.Go to the Service.Branding module, and in the lib/resources/atg/svc/
branding directory, edit the AtgServiceBrandingResources.properties file. Add the keys you entered above to this file for the panel name, title, etc.

21.Reassemble and deploy your EAR with the new module included, then start your Self Service server. The new panel should be included.

Note: All references in ATG Self Service point back to main.jsp. URL parameters are passed to indicate which tab to render. Any URLs that you include in your panel’s JSP must refer back to main.jsp and pass any attributes used by your page as well as those required by the application. Look at existing panel JSPs for implementation examples.

Re-branding ATG Self Service

The instructions in this section are intended for users who wish to modify the Self Service look without making any other customizations to the web application. These instructions are also applicable for remote hosting of images, which you might do for performance reasons.

There are two steps required in preparation to modify the look of the ATG Self Service application:

1.Copy the application style sheet and image directories to the location where you would like them to reside. These directories are in <ATG9dir>/Service9.4/Service/SelfService/reference/. The location to which you copy them should be Web accessible. This could be in the directory <ATG9dir>/home/doc/ or any other suitable location.

2.Create a file at <ATG9dir>/localconfig/atg/svc/self/ui/
SelfServiceUIConfiguration.properties containing the following lines:

imageLocation=<top-level image directory>


cssLocation=<css directory>

These directories do not have to be local. Note that the subdirectory structure under the image directory, including file names, must be preserved in order for the application to use any changed images without customization of the Web application itself.

If you need to rename the two style sheets used in the application, add the following lines to SelfServiceUIConfiguration.properties:

contentStylesheet=<replacement of styles.jsp>
outerStylesheet=<replacement of outerStyles.jsp>

You are now ready to make any desired changes to this style sheet and these images. The running application will reflect those changes.

ATG Self Service also supports the use of themes. To create a new theme, create a new subdirectory of the /css/ directory with the theme name as the directory name. Copy the two application style sheets into this directory and customize them as desired. To reference this theme rather than the default theme, add this line to the SelfServiceUIConfiguration.properties file:

theme=<theme name>

In this way, you can maintain multiple themes for the application in parallel. Use this mechanism to switch between the themes.

If you want to make these changes to a live configuration, you can edit these properties using the ATG Control Center (ACC) or using ATG Server Admin to browse to this nucleus component. Do this with extreme caution on production systems.

Starting Up ATG Self Service

It is best to run the production SelfServiceDataWarehouse module in a separate JVM instance than your Self Service server. Depending on the volume of reporting data to be summarized, you may want to dedicate one instance to an application that contains only the SelfServiceDataWarehouse module.

It is also possible to configure the SelfServiceDataWarehouse module to work in the same JVM as your Self Service Server.

The last two steps in this procedure specify modules to include in the Web application you build. For guidance on assembling applications, see the ATG Installation and Configuration Guide for your application server.

To run the Self Service application in one JVM and run a Self Service application or service.common and Self Service DataWarehouse in another JVM:

1.Configure each server’s properties to use same the same database by modifying the FakeXADataSource.properties file.

2.Disable user sessions for the second server. Refer to the ATG Installation and Configuration Guide for further information. (Skip this step if you are configuring a service.common and Self Service Data Warehouse JVM.)

3.Configure the lock manager by configuring one or more of your servers to start the /atg/dynamo/service/ServerLockManager at application startup. Modify the <ATG9dir>/home/servers/svcadmin/localconfig/atg/dynamo/service/
Initial.properties file:

#server/12.3.4.500
#/localconfig/atg/dynamo/service/Initial.properties:
initialServices+=ServerLockManager

4.Configure the ClientLockManager component in the <ATG9dir>/home/servers/svcadmindw/localconfig/atg/dynamo/service/
ClientLockManager.properties file for both servers to use the ServerLockManager:

$class=atg.service.lockmanager.ClientLockManager
lockServerAddress=12.3.4.500
lockServerPort=9010
useLockServer=true

Refer to the ATG Repository Guide for additional information.

5.Assemble, deploy, and start a Self Service application that includes the Service.SelfService module as outlined in the ATG Service Installation and Configuration Guide

6.Assemble, deploy, and start a Self Service Data Warehouse application that includes the Service.SelfServiceDataWarehouse module as outlined in the ATG Service Installation and Configuration Guide.

How to generate build.xml file

This example shows how to generate the build.xml file. You may say that build.xml file is the backbone of ANT (Another Neat Tool) technology. Each build.xml file contains only one project name and at least one target. The project tag has only three attributes:

Project

Attribute	Description	Requirement
name	project name	not necessary
default	target name which called by default	not necessary
basedir	the base directory having all path, it contain absolute path	not necessary

<project name="My Project" default="compile" basedir=".">


The project tag is used to create our project and its attributes are used to handle further processing of the project. The name attribute is used to specify the project name and the default attribute is used to specify which target will be called as default when the program will run and the basedir attribute is used to calculate the absolute path of the parent directory. 

An another tag is Target tag which has following five attributes:

Target

Attribute	Description	Requirement
name	target name	necessary
depends	depends on another target	not necessary
if	the name of the property that must be set in order for this target to execute.	not necessary
unless	the name of the property that must not be set in order for this target to execute.	not necessary
description	short description about target	not necessary

<target name="buildWar" depends="init" description="build a war file"/>

<target name="init" if="build"/>
<target name="init" unless="build"/>



In the target tag, name attribute is used for target name and the depends attribute is used to give sequence of target, i.e., which target will execute first, one target may depend on one or more other targets. The if attribute is used in case of condition, whether property exists or not; then this target will be executed and unless attribute is used as like else condition whether property does not exist, the target will not be executed and the description attribute is used for only giving details about target.

Next tag is property tag which has following four attribute:

Property

Attribute	Description	Requirement
name	name of the property, which is case-sensitive	not necessary
value	name of task attribute, this is done by placing the property name between "${"name }" in the attribute value	necessary
location	it contain property name	not necessary
file	name of the property file	not necessary

<property name="build" value="${build}"/> 

<property name="src" location="src"/> 

<property file="build.properties"/>

In the property tag, name attribute is used for property name; it is case sensitive. The value tag is used to give the task which will be the name of property in this format "${name}", and the location tag is used to specify the location of task where it performs and the file tag is used to import all properties of ant file. The complete build.xml file structure is as follows:

<project name="My Project" default="jar" basedir=".">

<property name="dir.src" value="src"/>
<property name="dir.build" value="build"/>
<property name="dir.dest" value="dest"/>

<target name="clean" description="Removing the all generated files.">
<delete dir="${dir.build}"/>
<delete dir="${dir.dest}"/>
</target>

<target name="prepare" depends="clean">
<mkdir dir="${dir.build}"/>
<mkdir dir="${dir.dest}"/>
<mkdir dir="${dir.src}"/>
</target>

<target name="compile" depends="prepare" description="Compilation of all source code.">
<javac srcdir="${dir.src}" destdir="${dir.build}"/>
</target>

<target name="jar" depends="compile" description="Generates news.jar file in to the 'dest' directory.">
<jar jarfile="${dir.dest}/news.jar" basedir="${dir.build}"/>
</target>

</project>

The above build.xml file is used to create directory, compile source code, create jar file and clean the directory if already exists. To check the program, simply copy and paste the above code and give appropriate path; then run with ant command on the command prompt. 

The output shows that a jar file named news.jar is created but in this jar file only manifest file is created. When you make a java file in the src folder and run with ant command, the jar file is created completely.

class Hello
{
  public static void main(String args[]){
  System.out.println("muraliraj");
  }
}

To check your program, compile it with ant command on the console; 


then the following output will be displayed:  Build Successful

Converting from Standard to Custom Catalogs

To use custom catalogs, you must convert your existing standard product catalog to the custom catalog configuration. The following steps describe how to perform this conversion.

Keep in mind that before you set up your custom catalogs for the first time, you should run the Catalog Maintenance Service as described in Using the Catalog Maintenance System.





Step 1: Add New Database Tables

Custom catalogs require some new database tables. These tables are defined in custom_catalog_ddl.sql. This script is located in the

<ATG9dir>/DCS/CustomCatalogs/sql/db_components/<db-vendor> directory.

Running this script adds the following tables to your database:

dcs_catalog

dcs_root_cats

dcs_root_subcats

dcs_sub_catalogs

dcs_category_info

dcs_product_info

dcs_sku_info

dcs_cat_subcats

dcs_cat_subroots

dcs_cat_catinfo

dcs_catinfo_anc

dcs_prd_prdinfo

dcs_prdinfo_rdprd

dcs_prdinfo_anc

dcs_sku_skuinfo

dcs_skuinfo_rplc

dcs_gen_fol_cat

dcs_child_fol_cat

dcs_catfol_chld

dcs_dir_anc_ctlgs

dcs_ind_anc_ctlgs

dcs_ctlg_anc_cats

dcs_cat_prnt_ctlg

dcs_cat_anc_cats

dcs_prd_prnt_cats

dcs_prd_anc_cats

dcs_cat_catalogs

dcs_prd_catalogs

dcs_sku_catalogs

dcs_user_catalog




Step 2: Run the Custom Catalog Migration

The Commerce Admin page includes a tool that automatically migrates your existing catalog to the new custom catalogs.

1.Specify the following module during application assembly:

DCS.CustomCatalogMigration

For more information on assembling applications, see the ATG Programming Guide.

2.Access the ATG Dynamo Administration page by pointing your browser to the URL appropriate for your application server. See the ATG Installation and Configuration Guide for the default port. For example, the default URL on JBoss is:

http://hostname:8080/dyn/admin

Note: your application must include the Dynamo Administration UI module in order for you to view this URL.

3.Click on the Commerce Administration link to open the ATG Commerce Administration page.

4.Select Standard to Custom Catalog Migration.

5.Enter the nucleus path to your catalog repository component in the Catalog Repository To Migrate: field.

6.Enter a display name for the new custom catalog.

7.Click on Migrate. Status updates display in the browser as the migration takes place.

Step 3: Assign Users to Custom Catalogs

You can set each user’s catalog manually or automatically. To automatically assign your customers to a custom catalog, use a scenario to set the catalog as soon as the user’s session begins. For information on scenarios, see the ATG Personalization Programming Guide.

Designing the Catalog Repository : A Simple Overview

If you are designing a multi-locale site with catalog repository content, you can set up your catalog repository in one of two ways. You can create a separate repository for each language or with a single repository for all languages.

A catalog repository is similar to other SQL repositories. There are three main parts:

The database schema on your SQL database server.

The repository component, which is of class atg.adapter.gsa.GSARepository.

The repository definition file, which is an XML file that defines the relationship between the SQL database and the Dynamo repository component.

This section discusses the pros and cons of single and multiple repository configurations. The option you choose dictates how you must set up your database tables. If you have a repository for each locale, you should also have database tables that contain different product information for each locale. If you have a single repository, you can separate your database tables so that the locale-specific properties of each product are stored in multi-valued tables that hold many different language versions of the same information. When you are designing your catalog repository, consider the following pros and cons of each design:

Multiple Repositories

Create a separate content repository for each language. This requires separate targeting rules for each locale, in which each rule references the appropriate language repository. This is the simpler of the two methods.

Pros: Separate targeting rules let you target different pieces of content to different locales. For example, site visitors from Japan may not be interested in the same style of jeans as site visitors from the US.

Also, administration of multiple repositories is easier than a single repository, because you can have a catalog administrator for each language who has access only to the appropriate repository.

Cons: You must maintain multiple copies of each item in the repository, since each item is duplicated in each locale-specific repository. In addition, storing separate values for each locale-sensitive takes up a lot of space in the database.

One Repository

Configure a single repository for all languages and include a language attribute in each repository item. This method requires you to develop logic that uses the RequestLocale’s localeString property to get the property values corresponding to the proper locale.

Pros: You can maintain only one copy of each repository item. These items draw their locale-specific attributes from a multi-valued table in the database.

Cons: This configuration is more difficult to administer because data for every language is in one repository. You cannot separate products that are Japanese-specific, for example.

You have to store most languages other than English in UNICODE format, which takes up 2 bytes per character, instead of ASCII, which only requires one byte per character. If you are using separate repositories, you can use ASCII and UNICODE where appropriate, but if you have a single repository you must store all data in UNICODE. This takes up more space in the database.

There are more database joins in a single repository because of the large number of multi-value tables. This slows Dynamo operation. The reduced performance may be imperceptible, but using multi-value tables does increase the load on the database.

Extending the Repository for Internationalization

To aid in internationalization, ATG Commerce includes a feature that allows you to specify alternate text for some catalog items using derived properties. You can add a derivation property to any property in the catalog, then specify alternatives to use in each catalog. For example, you could specify different display text to appear in different languages for the same catalog item.

The following example shows how to expand the displayName property to include English and German versions. As provided in ATG Commerce, displayName looks like this:

<item-descriptor name="sku"
  <table name="dcs_sku" type="primary" id-column="sku_id">
    <property name="displayName" column-name="display_name" data-type="string"/>
  </table>
</item-descriptor>

First, create two new properties, one for the English display name (reusing the column above) and one for the German display name (this requires a new table).

We start off with the name of the item descriptor containing the property:

<item-descriptor name="sku">

Remove the old definition of displayName. In order for the XML combination to work, do this inside the correct table tag:

<table name="dcs_sku" type="primary" id-column="sku_id">
  <property name="displayName" xml-combine="remove"/>

To reuse the column name for the English display name (this way the English values do not need to be copied anywhere), define the English display name in the same table tag, then close the table:

  <property name="displayName_en" column-name="dislpay_name" data-type="string">
    <attribute name="locale" value="en"/>
  </property>
</table>

Notice there is an attribute called “locale” on this property. The derivation method uses this to determine the correct value.

Now define the German version. It looks similar to the English version above (with a different “locale” attribute). Define a new table for this:

<table name="dcs_sku_de" type="auxiliary" id-column="sku_id">
  <property name="displayName_de" column-name="display_name" data-type="string">
    <attribute name="locale" value="de"/>
  </property>
</table>

Next, define the derived property. Giving it the same name as the previously English property (“displayName”) means that JSP code that references this does not have to be rewritten:

<property name="displayName data-type="string">
  <derivation user-method="atg.commerce.util.FirstWithLocale">
    <expression>displayName_en</expression>
    <expression>displayName_de</expression>
  </derivation>
    <attribute name="derivationAttribute" value="locale"/>
    <attribute name="keyService" value="/atg/userprofiling/LocaleService"/>
    <attribute name="keySubProperty" value="locale"/>
    <attribute name="defaultKey" value="en"/>
</property>

The <derivation> tag uses a custom derivation method called FirstWithLocale, a subclass of FirstWithAttribute. It performs the following actions:

1.Gets the repository key service

2.Calls RepositoryKeyService.getRepositoryKey, which returns the user’s current locale as the key.

3.Compares this key to each expression’s <locale> value.

4.Returns the first property whose attribute matches.

The locale is searched in a locale-specific way. For example, if locale=fr_FR_EURO, it first looks for a property where the locale attribute is fr_FR_EURO, then look for “fr_FR”, and finally look for “fr.”

There is also a defaultKey, which keyService uses if the if the value with the real key is null. In other words, if the real key is “de_DE” and we are looking for displayName, but displayName_de is null, then return displayName_en instead (assuming its locale is “en” and the defaultKey is “en” or “en_US”).

Using a defaultKey may slow performance. If no default key is defined, it is not used. If the default key is the same as the current key, there are no performance implications. In all other cases, there is an extra clause on all search terms.

The complete XML looks like this:

<item-descriptor name="sku">
   <table name="dcs_sku" type="primary" id-column="sku_id">
     <property name="displayName" xml-combine="remove"/>
     <property name="displayName_en" column-name="dislpay_name"
          data-type="string">
      <attribute name="locale" value="en"/>
    </property>
  </table>

  <table name="dcs_sku_de" type="auxiliary" id-column="sku_id">
    <property name="displayName_de" column-name="display_name" data-type="string">
       <attribute name="locale" value="de"/>
     </property>
  </table>


  <property name="displayName data-type="string">
    <derivation user-method="atg.commerce.util.FirstWithLocale">
      <expression>displayName_en</expression>
      <expression>displayName_de</expression>
    </derivation>
    <attribute name="keyService" value="/atg/userprofiling/LocaleService"/>
    <attribute name="defaultKey" value="en_US"/>
  </property>
   </item-descriptor>

Specifying Template Pages for Categories and Products

Category and product items create a navigational framework for customers. You can display categories and products on your commerce site using JSPs.

Rather than requiring you to create a separate JSP for each page on your commerce site, ATG Commerce enables you to create template pages that are filled in dynamically. For example, you could have a single template page for displaying any product. This page would have little or no static content; when the user selects a product, the page is filled in dynamically with information stored in the product’s properties. For example, the following JSP segment uses the ProductLookup servlet bean to display the current product, along with an image and a description.

<dsp:droplet name="/atg/commerce/catalog/ProductLookup">
<dsp:param param="itemId" name="id"/>
<dsp:oparam name="output">
  <p><b><dsp:valueof param="element.displayName"/></b>
  <p><dsp:getvalueof id="img13" param="element.smallImage.url"
          idtype="java.lang.String">
<dsp:img src="<%=img13%>"/>
</dsp:getvalueof>
  <dsp:valueof param="element.description"/>
</dsp:oparam>
</dsp:droplet>

You specify the template to use as a property of the category or product. This enables you to display any item without knowing in advance what template the item uses. For example, the following portion of a JSP uses a CategoryLookup servlet bean to retrieve the current category, and a ForEach servlet bean to create links to all of the child products of the category. The URL for each link is found by looking at the template.url property of the product being linked to.

<dsp:droplet name="/atg/commerce/catalog/CategoryLookup">
<dsp:param param="itemId" name="id"/>
<dsp:oparam name="output">
 <dsp:droplet name="/atg/dynamo/droplet/ForEach">
   <dsp:param param="element.childProducts" name="array"/>
   <dsp:oparam name="outputStart">
   <p><b>Child Products:</b>
   </dsp:oparam>
   <dsp:oparam name="output">
   <dsp:getvalueof id="a21" param="element.template.url"
        idtype="java.lang.String">
<dsp:a href="<%=a21%>">
   <dsp:valueof param="element.displayName"/>
   <dsp:param param="element.repositoryId" name="itemId"/>
   </dsp:a></dsp:getvalueof>
   </dsp:oparam>
 </dsp:droplet>
</dsp:oparam>
</dsp:droplet>

Defining Relationships between Categories and Products

The SQL Repository allows you to define properties that return repository items. The value of one of these items is the object ID. The SQL Repository can transform the ID into the repository item and return the actual object. This mechanism enables you to define the relationship between categories and products in many ways.

Most properties of the SQL Repository return values retrieved from the database. The SQL Repository also provides the ability to compute values of certain properties through Java code. Properties computed dynamically are called user-defined properties. This mechanism is used for the default definitions of several properties of the category and product items, to allow for dynamic definition of item relationships. For more information about user-defined properties, see the SQL Repository Item Properties chapter of the ATG Repository Guide.

Deriving the childCategories and childProducts Properties

The hierarchical relationships between categories and products are determined by their properties. The childCategories and childProducts properties of a category define the list of categories and products that are children of the category.

The childCategories property is a list of all categories that are children of the category. This is a user-defined property that is computed by the atg.repository.NotEmptyChooserPropertyDescriptor class, which sets the value of the property by merging the lists of categories in the fixedChildCategories and dynamicChildCategories properties. In the repository definition file, the definition of the childCategories property looks like this:

<property name="childCategories"
  property-type="atg.repository.NotEmptyChooserPropertyDescriptor"
  data-type="list" component-item-type="category" writable="false"
  queryable="false">
  <attribute name="properties"
    value="fixedChildCategories,dynamicChildCategories"/>
  <attribute name="merge" value="true"/>
</property>

This structure enables a page developer to refer to one named property (in this case, childCategories) whose value is assembled from different sources.

The fixedChildCategories property is an explicit list of categories you specify. The dynamicChildCategories property is a user-defined property that is computed by the atg.repository.GroupMembersPropertyDescriptor class. This class looks at the childCategoryGroup property, which specifies the name of a content group, retrieves the list of categories in that content group, and sets the value of dynamicChildCategories to that list.

This mechanism enables you to use business rules to determine the list of child categories. For example, you can create a content group that consists of categories that share a particular attribute, and set the value of childCategoryGroup to the name of this content group.

The childProducts property of the category is computed in the same way, using the fixedChildProducts, dynamicChildProducts, and childProductGroup properties.

For example, suppose your site has a category called Hats, and some of the hats are available all year, while others are seasonal. You could set the fixedChildProducts property of the Hats category to a list of the hats that are available all year. You could also create a content group called Seasonal Hats, which contains a list of hats that changes from season to season, and set the childProductGroup property of the Hats category to the name of this content group.

When a user accesses a page that refers to childProducts, Dynamo computes the current value of childProducts as follows:

1.Finds the current set of products in the content group specified in childProductGroup, and sets dynamicChildProperties to that set of products.

2.Sets childProducts to the merge of the set of products in dynamicChildProducts and the set of products in fixedChildProducts.

For more information about creating content groups, see Part 3: Performing Business User Tasks of the ATG Commerce Guide to Setting Up a Store.

Deriving the relatedCategories and relatedProducts Properties

In addition to the childCategories property, the category item has a property named relatedCategories. This property defines a list of categories that are related to the category, but which do not form a hierarchy with it. Related categories are useful for cross-selling. For example, if the Fruit category has Vegetables as a related category, you can use this relationship to display a link to the Vegetables category on the Fruit page.

The relatedCategories property is a user-defined property that is derived in a similar way to the childCategories property. The relatedCategories property is computed by the atg.repository.NotEmptyChooserPropertyDescriptor class, which sets the value of the property by merging the lists of categories in the fixedRelatedCategories and dynamicRelatedCategories properties. The dynamicRelatedCategories property is also a user-defined property, which the atg.repository.GroupMembersPropertyDescriptor class computes by retrieving the list of categories in the content group specified by the relatedCategoryGroup property.

The product item has a relatedProducts property that is computed in the same way, using the fixedRelatedProducts, dynamicRelatedProducts, and relatedProductGroup properties.

Removing the SQL Repository Definitions of User-Defined Properties

If you do not plan to use dynamically related products or categories on your commerce site, you can remove these properties from the repository definition. System performance improves when you simplify the data model to use only fixed relationships. For example, if all categories are explicitly related, you can remove the definitions of the childCategories, dynamicChildCategories, and childCategoryGroup properties, and just use the fixedChildCategories property, which you can then rename as childCategories.

Determining a Customer’s Locale

A customer’s locale determines the language that the customer sees when viewing a site in CRS. This
section describes how a customer’s locale is determined for each request.
Setting a customer’s locale is implemented through a series of includes. To start, an include-prelude
statement in the /WEB-INF/web.xml file specifies that the store.war/includes/prelude.jspf page
fragment should be included for all CRS JSP pages. prelude.jspf, in turn, includes the
store.war/includes/context.jspf page fragment. This fragment contains code for identifying and
setting the customer’s locale and it looks like this:

<%-- Identify and set customer's locale --%>
<dsp:importbean var="requestLocale" bean="/atg/dynamo/servlet/RequestLocale" />
<fmt:setLocale value="${requestLocale.locale}"/>
The context.jspf fragment invokes the /atg/dynamo/servlet/RequestLocale component
included in the Store.EStore.International module. RequestLocale is of class
atg.projects.store.servlet.StoreRequestLocale, which extends the
atg.userprofiling.ProfileRequestLocale class with the following logic that determines a user’s
locale:
· First, RequestLocale determines if a locale parameter is included in the HTTP
request. The locale parameter is embedded in the links associated with the language
picker on the store.war/navigation/gadgets/languages.jsp gadget. When a
customer clicks a language in the language picker, an appropriate locale is sent in
the ensuing HTTP request. (See Rendering the Language Picker in the Multisite
Features chapter for more details on the requests generated by the language picker.)

· If a locale is not present in the HTTP request, RequestLocale looks to see if a
siteId is included in the request. If a siteId is included, RequestLocale uses the
default locale for that site, as defined by the defaultLanguage property in the site’s
configuration.

· If neither a locale nor a siteId parameter is present in the HTTP request,
RequestLocale retrieves the locale from the customer’s profile.

· If a locale is not present in the customer’s profile, RequestLocale retrieves the
locale from the browser’s userPrefLanguage cookie.

· If the userPrefLanguage cookie is not present, RequestLocale uses the browser’s
default locale.

· If the browser does not have a default locale, RequestLocale uses its own default
setting, as specified by the optional defaultRequestLocale property in the
RequestLocale.properties file.

· Finally, if RequestLocale doesn’t have a default setting, it uses the JVM’s locale
default.

Once a locale is determined, RequestLocale sets the locale property in the customer’s profile and
writes a userPrefLanguage cookie to the browser that specifies the customer’s locale.
The context.jspf page fragment also calls the fmt:setLocale tag from the JavaServer Pages
Standard Tag Library (JSTL). This tag sets the locale for any additional fmt tags called for the remainder of
the request, such as the fmt:message tags that are used for displaying localized strings
Note: For more information on JTSL tags, see
http://java.sun.com/products/jsp/jstl/1.1/docs/tlddocs/index.html.

Content Targeters

After you set up user segments and content groups, you tell the system which content groups to show to whom and under which circumstances. You can do this is by setting up content targeters, which are business rules that you create through the Targeting and Segmentation option in the ATG Business Control Center. Content targeters define the content that you display to each user segment.

A content targeter can contain two kinds of business rules: show and hide. Each rule type is made up of specific conditions related to content, people, time, and environmental factors and generally reads as follows: Show/Hide this content… to/from these people… at these times… under these conditions. For example, suppose you wanted to show new feature articles (in a content group called newMemberFeatures) to registered site users (in a user segment called registeredMembers) every Monday. In this case, you could create a targeter called newFeatures with the following rule:


Show this content:
   items in group newMemberFeatures
to these people:
   people in group registeredMembers
at these times:
   every Monday of every month

When this targeter is invoked, it initially looks at all conditions except the content conditions. First, it checks to see if the registeredMembers property in the user’s profile is set to “true” (the people condition). If this or any other condition fails, the targeter completely ignores the rule. If the condition passes, it goes on to see if the current day is Monday (the time condition). If all of these conditions pass, the targeter looks at the content condition to determine the items to show or hide. In this case, it shows the user all items in the newMemberFeatures content group.

After you create a targeter, a page developer uses a targeting servlet bean to embed it in the appropriate site pages so that it will display the specified content to visitors who meet your targeting conditions. (Typically, page developers use the Document Editor window in the ATG Control Center to embed targeters in JHTML or JSP (JavaServer Page) files. For more information, see the ATG Page Developer’s Guide.)

Note: Multiple targeters can be used to produce a single Web page. For example, nine separate targeters are invoked to produce the “investor” home page (investorhome.jsp) in the Quincy Funds demo.

Using Scenarios to Match Content to Users

If you use the Scenarios module, you can match content to user segments in two ways: you can either create targeters (as described above), or you can use scenarios to achieve essentially the same results. The method you choose depends on whether you require the advanced features that scenarios provide, or whether the slightly simpler features of targeters meet your requirements. You can also set up a combination of the two methods. Note, however, that you create scenarios through the ACC, not through the ATG Business Control Center. For more information, see the ATG Personalization Guide for Business Users.

Creating a Content Group in BCC

Follow the procedures in this section to create a content group.

1. From the BCC Home page, select Personalization > Targeting and Segmentation.
2. Specify a name and an optional description for the project that will manage the creation and versioning of the new content group.
3. Select Content Groups from the Show list.
4. Click the Create New… icon and select Create New > Content Group.
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   1. Complete the fields in the General tab as follows.
      Name: Enter a name for the new group. The name can include spaces.
      Description: Enter some descriptive text to help identify the new group.
      Content Source: Select a repository from the Content Source drop-down list. The repository you select determines the content items, content type, and content properties that you can select for inclusion in this group when you define its rules (see the next section). The group can include only to items in this repository.
      Content Type: Select the type of content you want to be able to include. The type corresponds to the subset of items defined for the item descriptor type in the content repository definition file. Each item type has its own properties. For more information, refer to the ATG Repository Guide.
      Note that you cannot edit these settings after you have clicked the Create button to create the content group. Switching to the Rules tab also makes these settings permanent for this content group.
   2. By default, content groups are stored as files with the extension .properties in /atg/registry/RepositoryGroups. To change the folder where the new segment is stored, click Select Parent and specify the new folder.
      Note: If you need to change the location after the content group has been created, use the Move icon.
   3. When you have completed the fields in the General tab, click Create. The new content group appears in the Browse tab, and it is added to the project as an asset.
   4. Click Rules to display the Rules tab, and then follow the procedure in the next section, Defining Content Group Rules.
      Note that it is possible to continue to the Rules tab without clicking the Create button first; however, doing so means that the changes you have made so far are not saved, and the content group will be lost if your session ends or if you navigate to a different part of the UI. If you select Create, the new group is preserved, and you can continue the process of defining it at any time.