You are here:
URL Rules URL Syntax
You can define how your storefront URLs look in B2C Commerce via three types of URL syntax: standard B2C Commerce URL syntax, SEO URL syntax, or the deprecated search-friendly URL syntax. The syntax you use depends on which Business Manager module you have enabled.
- If you don't specify URL syntax, the B2C Commerce standard URL syntax is used.
- If you enable the URL Rules module, then the syntax configured for the URL Rules module is used. See Configuring Storefront URL Preferences.
- If you enable the deprecated SEO Support module (by de-selecting the URL Rules preference), then the syntax configured for the SEO Support module is used. See Enabling Search-Friendly URLs.
This page describes the URL rules syntax, and illustrates how it differs from the standard syntax and the SEO Standard.
Site URL Format
The site URL format is defined as follows:
Within B2C Commerce, you can configure and customize the endpoint of a URL.
Production instance URLs
On Production instances, B2C Commerce URLs look as follows:
Sandbox, Staging, and Development Instance URLs
You can define an alias (your.instance.hostname.example.com) on a
Staging, Development, or Sandbox instance. URLs have
your.instance.hostname.example.com as the host name, followed by the
prefix /s, followed by the site name. The actual endpoint is identical
to the one on the Production instance. This allows multi-site retailers to view the
configured endpoints for each of their sites.
If a custom hostname like example.com is used in the aliases file, the
URLs doesn’t require the pattern with the /s and site id in path and a
short URL is created like example.com/cart.
General Syntax Tips
To understand how requesting URLs are evaluated and resolved, see URL Evaluation and Resolution.
URLs can be resolved even if there are case differences in the URL.
URLs can be resolved if the following unencoded characters are in the URL, because B2C Commerce automatically encodes them:
, @ ) ! $ ' ( ~The use of spaces in a URL rule is for readability only. The absence of spaces around rule elements makes no difference whether your URL rule verifies. Commas however, are important because they separate the elements. The absence of a comma can determine whether your rule verifies.
When defining URL rules, be aware of context when you specify the source of the attributes. For a category rule, the source is a category, so you can use a rule such as the following:
[ [ constant, const ], /, [ category-path, [ attribute, ID ], - ]]In this rule, you are defining a constant and the category path to be used in every URL. The attribute in this rule is an attribute of the category, and thus the category ID.
In a product rule, however, the source is a product, so you must declare category as source for category-path, as in the following rule:
[ [ constant, const ], /, [ category, [ category-path, [ attribute, ID ], - ] ]]If you define the following product rule, then the constant
const111 applies as a constant and category applies
as you have specified in the category rule.
[ [ constant, const111 ], /, [ category] ]You need to be careful when defining the product rule because any usage of category
is as you defined it in the category rule. For example, if you specify the category
rule to result in /const222/electronics/ and then you use [ [
constant, const111 ], /, [ category] ] to define a product rule, then the results
are as follows:
/const111/const222/electronics/008884303996.html Multi-Value Attributes
When configuring SEO rules to generate URLs for products, content,
categories, and folders, you can specify multi-value attributes using
the Enum-of-String and Set-of-String
types in a way that is similar to single-value attributes. In the
following example, color is an Enum-of-String
product attribute.
[ [ category, [ attribute, displayName ] ], /, [ attribute, custom.color], /, [ attribute, name ] ] All values of the multi-value attribute are included into the URL. The values are concatenated by a blank, or the defined replacement character of blank (for example ‘-‘). The localized display value is used for the Enum values, unless no display value is defined, in which case the value is used.
An example URL, generated based on the rule above, is as follows:
/mens-shoes/black-yellow/spring-sneaker/12345.html Category URLs
URL Rules site URLs can be enabled for category pages, and merchants can configure the category URL endpoints on the URL Rules page Catalog URLS tab.
A standard B2C Commerce category URL with all SEO modules disabled follows this format:
www.sitegenesis.com/on/demandware.store/Sites-SiteGenesis-Site/default/Search-Show?cgid=mens-clothing-shortsA category URL with the deprecated SEO Support module enabled follows this format:
www.sitegenesis.com/mens-clothing-shorts,default,sc.html A category URL with the URL Rules module enabled follows this format:
[ category-path, [ attribute, displayName ], - ] This rule shows the category path and display name for the category, with a dash for the delimiter for spaces in the category name:
www.sitegenesis.com/mens-clothing-shortsTo define the content of a category URL, you can combine multiple elements and specify the delimiters between the elements.
[ [attribute_1], del , [attribute2], del , [attribute_3] ]The rule can contain up to five elements. Category elements have four types: attributes, constant, category-path, category-parent. (See below for a specification of each of those element types.)
Examples:
[ [constant, shop], / , [category-path, [attribute, ID], -] ]www.sitegenesis.com/shop/mens-clothing-shorts/ If you would like to exclude certain categories or folders from the URLs, you can use the path exclusion category syntax.
A simple syntax of:
[ category-path, [attribute, displayName], /, [3,4]]will take a category tree of brand > sale > men > shoes > leather, and display the URL as:
www.sitegenesis.com/brand/sale/leatherThis syntax is available for configuration for the following URL rule attributes:
- category-path
- category-path-with-offline
- folder-path
- folder-path-with-offline
The following configuration options are available to define category URLs:
A setting is provided to optionally append a trailing slash to category URLs in the URL Rules page Catalog URLs tab.
www.sitegenesis.com/mens-shorts (trailing slash off)www.sitegenesis.com/mens-shorts/ (trailing slash on) If a site is localized, then a separate URL exists for each site locale, for example:
www.sitegenesis.com/en/mens-clothing-shortswww.sitegenesis.com/de/herren-kleidung-shortsYou can control how the locale is specified for the URL in the URL Rules page Settings tab. You can set whether your sites are localized using the Global Preferences Locales page.
URL generation behavior for rules using a category path typically skips offline categories, which can result in categories flagged as conflicting, even when they actually are not in conflict. This can occur when a merchant needs to keep categories offline until a specific event. They typically use a standard structure for subcategory names within each event-related category, for example, MothersDay/sale, ValentinesDay/sale, Easter/sale.
For example:
- Category A (offline) has a subcategory
a-salewith display nameSALE. When A changes to online, the a-sale category has the URLa/sale. - Category B (offline) has a subcategory
b-salewith display nameSALE. When B changes to online, the b-sale category has the URLb/sale.
Because both A and B are offline, a-sale and b-sale will have the same URL
sale. This pollutes the URL conflicts log with wrongly identified
conflicts, making it difficult to identify genuine URL conflicts.
You can define rules that obtain information from offline categories/folders, as shown in these examples:
[ category-path-with-offline, [ attribute, displayName ], / ]
[ category-parent-with-offline, [ attribute, displayName ], / ]
[ folder-path-with-offline, [ attribute, displayName ], / ]
[ folder-parent-with-offline, [ attribute, displayName ], / ]For example, the sale category is offline, and this is the category taxonomy:
host.com/sale/mens
host.com/mensWhen offline categories are recognized, the results are not in conflict: no URL conflict resolution is required.
host.com/sale/mens
host.com/mensWhen offline categories are not recognized, conflicts result, which can be handled via URL conflict resolution.
host.com/mens-1
host.com/mens-2 Based on the category URL rule, B2C Commerce automatically generates category URLs. You can also define the URL endpoint for any category.
For example, the following rule:
[ attribute, displayName ]leads to a conflict for the Sale category in and , and the URL generator automatically appends an index number to the generated URLs: You can override the generated URLs for or . The PageURL attribute for the category is used as the endpoint, instead of the endpoint generated by the rule.
- Generated URL of :
www.sitegenesis.com/sales-1 - Generated URL of :
www.sitegenesis.com/sales-2
Example 1: Men’s Sales
Assume the generated URL of is:
www.sitegenesis.com/sales-1 However, if you set the PageURL attribute of the category to mens-sales, then the actual URL of is:
www.sitegenesis.com/mens-sales Example 2: Women’s Sales
Assume the generated URL of is:
www.sitegenesis.com/sales-2 However, if you populate the PageURL attribute for the category with womens-sales, then the actual URL of is:
www.sitegenesis.com/womens-salesProduct URLs
URLs can be enabled for product pages. The product URL endpoints are configured based on a simple rule syntax.
Product URLs are enabled using a preference in Business Manager and configured on the URL Rules Page Catalog URLs tab. In the following example, a product URL contains its category, its name, and the product ID. The product ID is mandatory and is appended to each product URL, along with the extension .html.
URL Rule:
[ [category], /, [ attribute, name ] ]Example URL:
www.sitegenesis.com/mens-clothing-shorts/straight-fit-shorts/8353682.html You
can configure if the delimiter in front of the product ID is '/' or '-'. If the
delimiter is '-', but a product name contains '-', then B2C Commerce automatically uses
the '/' delimiter for the URL of this product.
www.sitegenesis.com/crowne-shorts-brown/83536828.html instead
of www.sitegenesis.com/crowne-shorts-brown-83536828.html
To define the content of a product URL, you can combine multiple elements and specify the delimiters between the elements.
[ [attribute_1], del , [attribute2], del , [attribute_3] ] The rule can contain up to five elements. Elements have two types: attributes and category.
The following configuration options are available to define product URL endpoints:
| Option | Definition |
|---|---|
| category | Examples : For the following rule, select the Use '-' as Product ID separator instead of '/' checkbox. If the checkbox isn't selected, you see the following: |
| attribute | This element is used to include category information. Examples The category URL as generated by the category URL generator (see previous section). This rule must be used when the URL is supposed to “show the product in category context”. The display name of the category. The URL name of the category and an extra custom attribute of the category. |
| constant | This element is used to include an arbitrary text element. You can also use the category with the constant element. |
B2C Commerce determines the category in the URL using the following logic:
- Use the primary category of the product in the storefront catalog.
If the product doesn't have a primary category assigned or the primary category doesn't exist in the storefront catalog, move to the next step.
- Use the classification category of the product in the storefront catalog.
If the product doesn't have a classification category assigned or the classification category does not exist in the storefront catalog, move to the next step.
- Use the first category in the storefront catalog ever assigned to the product. The product must be assigned to at least one category in the storefront catalog to be available on the site.
Similar to category URLs, you can override the product URLs generated by the URL generator by using the PageURL attribute.
Generated URL of product:
www.sitegenesis.com/sports-shoe-red/1234.html
PageURL attribute of product: mckenzie-sports-shoe
Actual URL of : www.sitegenesis.com/mckenzie-sports-shoe/1234.html
Content and Folder URLs
URL definition/generation for folders and content assets functions the same way as categories and products. See the URL Rules page, Content URLs page in Business Manager for folder and content URL rule examples.
Pipeline Aliases
All page URLs except product, category, and content pages show a pipeline in the URL.
For pipeline pages, you can create URLs that don't contain
/on/demandware.store by mapping a pipeline name to an alias in
Business Manager. Pipeline page URLs look similar to:
www.sitegenesis.com/on/demandware.store/Sites-SiteGenesis-Site/default/Account-Showwww.sitegenesis.com/on/demandware.store/Sites-SiteGenesis-Site/default/Search-Show?q=shoesIn Business Manager, you can define mappings for any of your pipelines.
| URL | Pipeline |
|---|---|
| account | Account-Show |
| search | Search-Show |
| wishlist | Wishlist-Show |
If new URLs are turned on, and a mapping has been defined for a pipeline, the URL changes to the following format:
www.sitegenesis.com/account
www.sitegenesis.com/search?q=shoesLocale
You control if and how the locale/language identifier is represented in all storefront URLs, by selecting a locale option: None, Hostname, URL Parameter, or Path.
The None option is used if the site has only one presentation language. Incoming URLs are not examined for any language identifier. All pages are delivered in the site default locale. B2C Commerce assumes that there is only one allowed site locale, but if there are multiple, the default one is used. Generated URLs will not contain any locale identifier.
www.example.com/mens For Hostname, the presentation language is determined by examining the host name of the incoming URL. You must configure a mapping between host names and site locales, for example de.example.com - de_DE, www.example.com - en_US, es.example.com - es_US. Multiple host names can be mapped to one locale. If no mapping exists for a host name, the page is delivered in the default site locale.
www.example.com/mensde.example.com/mensFor URL Parameter, the presentation language is determined by
examining a standard URL parameter of the incoming URL. The default parameter name is
"locale", ?locale=en-US, and you can specify another query string
parameter name, such as "lang". You can configure a mapping of a language code for any
custom string to a site locale, for example default <> en_US, es <> es_US.
If no mapping exists, it's assumed that the locale ID is specified. If the locale id
doesn't match any of the allowed site locales, the page is delivered in the default site
locale. Generated URLs contain the same URL parameter as the incoming URL if the prefix
was valid, or the prefix defined for the site default locale if the prefix was invalid.
You can define the name of the URL parameter.
www.example.com/mens?locale=en-USde.example.com/mens?lang=enwww.example.com/mens?lang=spanishFor Path, the presentation language is determined by examining
the first element in the URL path. You can configure a mapping of the URL language code
to a site locale, for example default-> en_US, en ->
en_US. If no mapping exists, it's assumed that the locale ID is specified in
the URL. If the locale id doesn't match any of the allowed site locales, the page is
delivered in the default site locale.
www.example.com/de/menswww.example.com/en/mens Define a double-path locale by specifying the first value, the '/'
character, and then the second value. For example,
en/US or de/DE, which results in
the following:
www.example.com/en/US/menswww.example.com/de/DE/mens