Constructing SEO-friendly URLs by using pattern files

Pattern files are used in the construction and deconstruction of SEO-friendly URLs. Because each page type requires the construction of different data, a pattern file contains a URL template. For example, there are pattern files for the Category page, Contact Us page, and Product page.

Pattern definitions

The following code snippet is a sample pattern definition for a privacy policy page URL: 

<!-- Privacy URL like this: http://localhost/shop/en/aurora/privacy-policy-registration (canonical)
This Pattern is replacement for PrivacyPolicy mapping present in SEOURLMapper.xml in previous SEO implementations 
(Before FEP3)
 -->
	a<seourl:seoUrlPatternDef name="PrivacyRegistrationURL">
		b<seourl:seoUrlPattern viewName="PrivacyView">
               /LanguageToken/StoreToken:CatalogToken/PrivacyRegistrationToken</seourl:seoUrlPattern>  
		c<seourl:urlToParamMapping>
			<seourl:mapping name="langId" value="?LanguageToken?"/>
			<seourl:mapping name="storeId" value="?StoreToken?"/>
			<seourl:mapping name="catalogId" value="?CatalogToken?"/>
			<seourl:mapping name="fromPage" value="registration"/>
		</seourl:urlToParamMapping>
		d<seourl:paramToUrlMapping>
			<seourl:mapping name="LanguageToken" value="?langId?" defaultValue="-1"/>
			<seourl:mapping name="StoreToken" value="?storeId?"/>
			<seourl:mapping name="CatalogToken" value="?catalogId?"/>
			<seourl:mapping name="PrivacyRegistrationToken" value="Privacy-Policy-Registration"/>
		</seourl:paramToUrlMapping>
		e<seourl:usageDef>
			<seourl:usage device="browser">
				<seourl:target>Privacy</seourl:target>
			</seourl:usage>
		</seourl:usageDef>
	</seourl:seoUrlPatternDef>
a. SEO URL pattern definition name
The name of the pattern. Set the value to be the name that is used when you construct the SEO URLs in JSP pages by using the wcf:url tag library.
b. Struts to pattern mapping
Defines the pattern of the URL. The viewName attribute defines the struts action mapping that is used when the SEO URL is deconstructed. After the SEO URL is deconstructed and matched against the pattern, the request is forwarded to the corresponding viewName attribute.
c. SEO URL to parameter mapping
Used during deconstruction of the SEO URL. After the URL is matched against the pattern, the values that are associated with the keywords in the URL are attached to the corresponding parameter names. The parameter names are defined in this mapping, which is based on the mapping between the tokenName and the keyword.

For example, if en/aurora/Privacy-Policy-Registration is matched against the preceding pattern /LanguageToken/StoreToken:CatalogToken/PrivacyRegistrationToken, the value of keyword "en" is associated with parameter langId. The aurora keyword is associated with StoreToken:CatalogToken and its value (for example: 10001:10002) is assigned to storeID and catalogId (storeId = 10001 and catalgoId = 10002) after splitting.

d. SEO URL parameter to URL mapping
Used during construction of the SEO URL in JSP pages by using the wcf:url tag library. Based on the token name and tokenValue, the keywords are looked up in the database and substituted for the token names in the URL pattern.
e. Pattern usage
In this example, the usage is for a privacy static page, which is displayed under the Store Management tool in Management Center.

Structures of pattern files

Pattern files are in this directory:
  • LinuxAIXWindowscrs_eardir/crs-web/WEB-INF/xml/seo/stores/storedirectory
  • HCL Commerce Developerworkspace_dir\crs-web\WebContent\WEB-INF\xml\seo\stores
You can have more than one pattern file for a store, and each file is read in alphanumeric order. If any customization is required to the default patterns, create a separate file and ensure that it is listed last alphanumerically to overwrite the default definitions.
If no pattern file is found, a lookup searches the store directories for a pattern file. The pattern file lookup continues until one of the following conditions is satisfied:
  • Pattern files are found at some level. The maximum number of levels that can be defined in an SEO URL is 5.
  • A .disable file is found.
  • All the related store directories are searched.

HCL Commerce EnterpriseIn an extended sites store, the pattern file lookup first searches the store directories for the extended sites store. If no pattern file is found, the lookup then searches the asset store directories.

Fixed tokens

An SEO pattern file can contain two sections: A token is an elementary symbol in a URL pattern. Each token has a specific usage and is associated with a keyword and a value. During SEO-friendly URL construction, the tokens in a URL pattern are replaced by their respective keywords. During URL deconstruction, the keywords are looked up for their respective token names to match a particular URL pattern. The keywords are also looked up to find the values that are to be associated to the parameters of the deconstructed dynamic URL. There are two types of tokens: dynamic and fixed. Dynamic tokens are defined in the SEOTOKENUSGTYPE table, and the fixed tokens are defined in the pattern file. 
<seourl:tokenDef>
		1<seourl:token name="PageViewToken">
			<seourl:tokenValue value="image"/>
			<seourl:tokenValue value="detailed"/>
		</seourl:token>

		2<seourl:token name="PrivacyRegistrationToken">
			<seourl:tokenValue value="Privacy-Policy-Registration"/>
		</seourl:token>
		
		3<seourl:token name="TopCategoryBooleanToken">
			<seourl:tokenValue value="Y"/>
			<seourl:tokenValue value="N"/>
		</seourl:token>

		4<seourl:token name="BeginIndexToken">
			<seourl:tokenValue value="[[0-9]*]"/>
		</seourl:token>
		
		5<seourl:token name="CatEntryIDToken">
			<seourl:tokenValue value="[[0-9]*]"/>
		</seourl:token>
		
		6<seourl:token name="ContentOnlyToken">
			<seourl:tokenValue value="1"/>
			<seourl:tokenValue value="0"/>
		</seourl:token>
	</seourl:tokenDef>
1. PageViewToken
Can have only two values, image or detailed.
2. PrivacyRegistrationToken
Can have only a value of Privacy-Policy-Registration.
3. TopCategoryBooleanToken
Can have a value of Y or N.
4. BeginIndexToken
Can have numerical values. Enclose the expression in a set of brackets []. The expression [[0-9]*] indicates that the valid value for BeginIndexToken can be any numerical value. To use an integer, do not use the *.
5. CatEntryIDToken
Can have numerical values. Enclose the expression in a set of brackets []. The expression [[0-9]*] indicates that the valid value for CatEntryIDToken can be any numerical value. To use an integer, do not use the *.
6. ContentOnlyToken
Can have a value of 1 or 0.
A value of 1 indicates to include header, footer, left and right navigation bar, along with content.
A value of 0 indicates to not include the header, footer, and left navigation bar. Display the content present at the middle of the page

Dynamic tokens

The SEOTOKENUSGTYPE table bridges the gap between the Management Center user interface, which saves the URL keywords, and the pattern definition files that are defined in the storefront. The primary gap between Management Center and the storefront is the token names that are used in the pattern definition files. The Management Center user interface uses the token names to save the URL keywords for catalog entries, category, and static store pages. To distinguish among the various tokens that are used in the pattern definition, the concept of usage is introduced. The token Usage Type table supplies the Management Center user interface with the token names used in the pattern definition files. The usage maps a token name to the entities for which the keywords are defined against the set token name. Some of the usages are predefined in this table and are mapped to the default entities for which the URL keywords are allowed to be defined.
These following predefined usages are found in the table mapping:
  • Store
  • Language
  • Product
  • Item
  • Category
  • Privacy
  • Sitemap

Usage is defined for entities such as catalog entries and categories and for static content in the store, such as privacy pages or site map pages.

The token usages are defined at the store level. Similar to the view store relationship, you can define token usages at the site level and are applicable to all the stores. You can add more usages to the default usage list. You can also override the token names for these usages for a specific store or for the site.

The store tokens are cached in the SEOConfigurationRegistry instead of the dynamic cache because the tokens are infrequently updated. Always define store tokens at the site level (zero store-level) because store tokens are always used to resolve the storeId.

The predefined store usage uses StoreToken as the token name. If any complex tokens are defined for the store usage for a specific store, they must contain the StoreToken. For example, a store might consider merging the store, language, and catalog Id values into the token for the store usage and takes the following form: StoreToken:LanguageToken:CatalogToken. When the configuration registry caches the token, it looks for the StoreToken string in the token name. The value at the corresponding position in the token value is treated as the storeId. This behavior is the primary reason for a hardcoded token name as the predefined store token.

Languages

The default token for the language usage is LanguageToken. Because the keywords for the language token are taken from the language registry, you do not have to define them.

By default LanguageTokens are taken from the language registry. The lang code is the keyword. For example, in English, the urlKeyword is en and languageId is -1.

But this default behavior can be overridden by defining separate urlKeywords (other than the default language code) for any language, in SEO URL Pattern files.

For more information, see Using new languages with SEO-friendly URLs.

Best practices for working with pattern files

Pattern files provide various options. These options can be an area of uncertainty for users who must decide how to construct the URLs.
  • Pattern files are read when a request is first made. If the pattern files are modified after this request, the changes are not reflected in a store until the server starts or restarts.

    If you are working within a development environment, you can include a text file that is named .reload to have your environment load the changes within the pattern files periodically.

    The .reload file should be located in the same directory as your pattern file.

    Within the .reload file, specify the reload interval property with the following format: 
    reloadinterval = reload interval in seconds
    Where reload interval in seconds is the time (in seconds) that elapses before the pattern file is reloaded. For example, 
    reloadinterval = 900
    The .reload file is for use in loading changes within SEO pattern files. This file does not load changes within the SEOURLMapper.xml file.
    Note: Use the .reload file only during development, do not use the file in a production environment. Constantly reloading the pattern files can severely affect performance and can cause unexpected results.
  • Adding an empty .disable file in the same path, disables the new SEO feature for that particular store. This action requires a server restart or a .reload file.
  • Ensure that the value of the patternName is not the same as any action mapping name in the Struts configuration files.
  • The forward slash ' / ' and underscore ' _ ' characters are special keywords that are used to separate tokens in the SEO pattern files. For example, 
    <seourl:seoUrlPattern viewName="ProductDisplay" >/LanguageToken/StoreToken:CatalogToken/CatEntryIDToken</seourl:seoUrlPatter>
    Note: Do not use these characters, or the dot ' . ' character when you are constructing the value of a urlKeyword