Seen from a historical perspective, the URLs in Intershop have been fairly long ever since. They contain parameters to specify a locale, a currency, an application, sites or service types, like, for example:
http:// www.example.com/INTERSHOP/web/WFS/PrimeTech-PrimeTechSpecials-Site/en_US/-/USD/ViewStandardCatalog-Browse?CategoryDomainName=PrimeTech-Computers&CategoryName=Notebooks (Standard Intershop URL).
Modern SEO concepts require to avoid URLs like this. Instead, they recommend using short, structured and readable URLs. In order to fulfill these requirements, Intershop provides four concepts to handle URLs.
Info
For newer versions of this feature refer to the following documents:
Intershop 7.4 introduces the following new features:
domainsplitting
separated by spacesshortpathpattern
) for local rules, domainsplitting
or globallylocale
, currency
and appurlid
via domainsplitting
configurationMigration hints:
Definition of a global parameter rules.shortpathpattern
is necessary to enable the feature improved domain splitting, like
rules.shortpathpattern = /${group}/${domain}/${locale}/${appurlid}/${currency}${path}
.hideDefaultApplicationID
and .domainsplitExpandPattern
are not supported anymore.rules.shortpathpattern
instead.domainsplitting.rule.<name>.
is deprecated.rule.<name>.
instead.The concept is divided into five parts covering: URL configuration, short links, URL rewriting, domain splitting and special link rewriting.
URLs in Intershop start out with protocol, server name and, optionally, a port. The following parameters, "prefix" and "service type", are set using URL configurations.
http[s]://[server name]:[port]/[prefix]/[service type]/[server group]/[site id]/[locale]/[application id]/[currency]/[action]?[parameters]Example:
https://www.example:443/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/de_DE/-/USD/ViewUserAccount-Start?targetPage=HomepageIn order to apply rules to every single URL in the application, there must be wrappers for each used link throughout the application. It is strongly recommended to use these functions at any place. Do not try to hard-code URLs. Whenever URL rewriting is enabled, these wrappers perform the URL transformation. The functionality is available for ISML templates, pipelets and through Java code.
In ISML templates, the following ISML functions can be used to render links:
url(<Action>,<Parameters>)
creates a link with the default port and protocol.
<a href="#url(action('ViewBasketHistory-Start'))#">View Basket History</a>
urlex(<protocol>, <port>, <Action>, <Parameters>)
can be used to specify a specific protocol (http/https) or a specific port.
<a href="#urlex('https', '443', action('ViewProduct-Start'))#">View Product</a>
The CreateURL
pipelet is used for creating rewritten links at pipeline level.
For Java, there is a URLComposition implementation that can be instantiated to create a URL using the following code snippet:
Parameters params = new Parameters(); params.add("sku", "prod_1234"); Action action = new Action("ViewProduct-Start"); URLParameterSet urlParameters = new URLParameterSet(); URLComposer composer = getTemplateExecutionConfig().getURLComposer(); // recommended String compactedURL = composer.createURL(true, "https", null, "443", action, urlParameters);
Beginning with Intershop 7.3.1, there are two different components for displaying rewritten links on the storefront, without knowing the URL rewriting rules. A specific syntax is used that helps rendering links - "Navigation - Simple Link" (since 7.x) and "Common - Freestyle HTML Text" (since 7.3.1).
Within these components, the following code can be used to render different URLs. The parameters
and the anchor
are optional.
http://<url>?<parameters>#<anchor> https://<url>?<parameters>#<anchor> pipeline://<action>?<parameters>#<anchor> page://<page_id>?<parameters>#<anchor> product://<sku>?<parameters>#<anchor> category://<category_id>@<domain>?<parameters>#<anchor> image://<site-name/subfolder/file-name.extension> // "image" introduced in IS 7.7
In the "Freestyle HTML Text", these links can be used as follows:
<ul> <li><a href="http://www.google.de">http | www.google.de</a></li> <li><a href="https://mail.google.com">https | mail.google.com</a></li> <li><a href="page://page.returnpolicy">page | return policy</a></li> <li><a href="product://10666805@PrimeTech-MasterRepository">product | A-DATA 750GB SH14</a></li> <li><a href="category://897@PrimeTech-PrimeTechSpecials-Telecommunication">category | Tablet PCs</a></li> <li><img href="image://inSPIRED-inTRONICS-b2c-responsive/teaser/home_teaser_1.jpg" alt="teaser"></li> <!-- "image" introduced in IS 7.7 --> </ul>
These links are converted to valid storefront URLs.
URL configuration concerns the naming of prefix and service type in a standard URL.
The default URL prefix is INTERSHOP
. The specified service type determines how different requests are handled. The (default) URL prefix and the service types are listed in the following table, together with their corresponding configuration parameter names.
Parameter | Service Type | Value | Description |
---|---|---|---|
intershop.urlmapping.urlPrefix | x | /INTERSHOP | User-adjustable URL part |
intershop.urlmapping.pipeline.webadapter | Pipeline | /web | Calling pipelines |
intershop.urlmapping.servlet.webadapter | servlet | /servlet | Servlets |
intershop.urlmapping.static.webadapter | static content | /static | File system resources like pictures |
intershop.urlmapping.wsrp.webadapter | WSRP | /wsrp | WSRP (portal-) requests |
intershop.urlmapping.rest.webadapter | REST | /rest | REST requests |
intershop.urlmapping.dist.webadapter | dist | /dist | Static system resources |
intershop.urlmapping.wastatus.webadapter | wastatus | /wastatus | Load balancer requests |
intershop.urlmapping.wastatistics.webadapter | wastatistics | /wastatistics | Statistics on Web Adapter (WA) |
Checking statistics on the Web Adapter uses the following URL: /INTERSHOP/wastatistics.
The URL configuration has no side effects. Hence, renaming in an SEO compliant manner is possible at any time.
All configurations for URL configuration are done in the appserver.properties, which is read once during the application server start.
The appserver.properties include the following required parameters:
intershop.urlmapping.urlPrefix
is the basic parameter that defines the first adjustable part of the URL.intershop.urlmapping.<Service Type>.webadapter
specify the names for the different service types.intershop.urlmapping.<Service Type>.appserver
should not be changed. They allow merging this feature into different projects. Also, Intershop Studio uses these parameters to read the configuration.intershop.template.WebRootURL
and intershop.template.HttpsWebRootURL
are the parameters for accessing static content.Before debugging pipelines with Intershop Studio, please update to the latest version of Intershop Studio.
intershop.urlmapping.static.webadapter
, which should be set to /is-bin/INTERSHOP.servlet
by default.The purpose of short links is to shorten URLs by providing a pair of URLs. When a URL is called on the Web Adapter, it will try to resolve a short link source URL (comparing the called URL with the short link's source URL) and then propagate the call to its target URL. The target URL is actually set by replacing the matching "source URL" part with the target URL.
For marketing purposes, short URLs to a specific page are used, for example, providing a very catchy URL to a promoted product. Another scenario is to have a more convenient access to certain URLs.
Example:
SourceURL | http://myhost/inSPIREDStorefront |
TargetURL | http://www.example.de/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/Default-Start |
The user may also provide just relative URLs, keeping them independent from the server.
SourceURL | /inSPIREDStorefront |
TargetURL | /INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/Default-Start |
As parts of the URL may depend on the server configuration, it is recommended to store short links in relation to their host names (bold marked).
/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/Default-Start |
This way you can enter the target links via the Commerce Management application as they appear upon browsing. The system will ensure that it is saved in a server-independent manner. Technically spoken, a relative representation is used with placeholders.
As a third way, target URLs can point to rewritten URLs (see Concept - URL Handling (valid to 7.7)#URL Rewriting).
SourceURL | inSPIREDStorefront |
TargetURL | inTRONICS-Site-WFS-en_US-USD |
As short links are typically marketing-driven, they also provide the ability of setting a validity period (i.e., start date and end date) during which the short link is valid. This can be coupled closely to the marketing period of a product (e.g., a promotion) providing a short link during this period. An additional feature is that the short link manager can decide how the source URL is routed to the target URL:
Type | Code | Method | Name | Description |
---|---|---|---|---|
none | 200 | wainclude | OK | Includes the target page instead of redirecting the browser |
default | – | redirect | OK | Redirecting to a page that can optionally define its own return code xyz |
301 | 301 | redirect | Moved permanently | Indicating that a link has moved to a new location |
302 | 302 | redirect | Moved temporarily | Requested information is found at a different location (routing) |
Note
It may take up to 15 minutes until Short Links become inactive. Alternatively, clean up the page cache.
Note
Demo Short Links are created via DBInit for the B2B and B2C Demo channels. These can be managed in the Commerce Management (Channel | Marketing | Link Management | Short Links).
In addition there are also Short Links created via DBInit for SMC and Operations (SLDSystem) which cannot be managed:
SourceURL: /Operations
TargetURL: /INTERSHOP/web/WFS/SLDSystem
SourceURL: /SMC
TargetURL: /INTERSHOP/web/WFS/SMC
From the SEO perspective, a qualified URL is short and readable, as well as contains enough semantic information to describe the content of the address. Since the standard Intershop URLs do not match these criteria, they have to be rewritten.
In Intershop 7.8, the classic URL Rewrite Handler is still available, but deprecated. For the new URL Rewrite handler, there is a Migration Guide Recipe and a separate Concept - URL Rewriting (from 7.10.5).
URL rewriting can be activated for a storefront site using three different ways: the Central Administration Frontend (since 7.6 Organization Management), the SMC (since 7.6 System Management) or using site-specific preferences.
Logging into the SMC or OMA (formerly known as CAFE) - the interfaces are similar - enables the user to change the URL rewriting status as well as the "URL Rewrite Site Name".
To do so, navigate to Site Management | inSPIRED-inTRONICS-Site.
Using the site preferences, the following parameters can be set: URLRewriting, URLRewriteHandler, URLRewriteSiteName. Developers and administrators can configure these settings using the Intershop Studio Site Explorer.
To do so:
Changing the handler class or site name shortcut requires the server to be restarted, whereas toggling the URL rewriting status can be performed at run-time.
An initial set of rewrite rules is already deployed in the cartridge sld_ch_b2c_app, targeting the URLs for the demo storefront inTRONICS. This set of rules serves for demonstration purposes and can be reused as a starting point for defining project-specific rewrite rules.
In contrast to previous Intershop software versions, the predefined rule set does not only address search engine-relevant content (homepage, catalog and product URLs) but also all kinds of content URLs, as required by customers to meet SEO and marketing criteria having short and readable URLs. As opposed to Enfinity Suite 6.4, "domain split" URLs and "non domain split" URLs can now be handled with the same rule set. This saves time for developing and administrating rewrite rules.
Configuring
The fine tuning of URL rewrite rules can be done using the urlrewrite.properties files. These files are located in the following places:
<SERVER>\share\system\config\cluster\ <CARTRIDGE>\release\urlrewrite\
Intershop provides a default URL Rewrite Handler implementation. This implementation defines URL rewriting via predefined pattern-matching and text processing rules (rule-based URL rewriting). Using this handler, existing storefronts can easily be optimized by simply defining URL rewrite rules in urlrewrite.properties files instead of providing Java rewrite code.
Projects in the past showed that all customer needs were met when using the default rewrite handler. Unless there are extraordinary requirements on URL definitions, a custom URL rewrite handler is not required. The assignment of a rewrite handler to a site is done by preferences that can be set in Intershop Studio.
The default URL rewrite handler can use (multiple) urlrewrite.properties file(s) as input. These files can be located at different locations:
Location | Description |
---|---|
<cartridge>/staticfiles/cartridge/urlrewrite/ | Multiple files allowed. Usually a single file is used, which is located in the sld_ch_b2c_app cartridge. |
<server>/share/system/config/cluster/ | Recommended to contain the domain splitting settings. |
The urlrewrite.properties files contain settings at different levels (or scopes):
# Global settings: Slashes are replaced in all rules rules.replaceSlashes = true # Local rule "home" setting: Overrides the global setting of "replaceSlashes" rule.home.replaceSlashes = false # Global domainsplitting settings: verwriting the global settings for all domainsplitting rules domainsplitting.host_de.replaceSlashes = false # Local domainsplitting rule "home" overwrites the global domainsplitting setting rule.domainsplitting.home.replaceSlashes = true
The following list describes the different scopes.
Scope | Type | Description |
---|---|---|
rules.<parameter> | Global setting | Global parameters can be overwritten by local parameters |
rule.<name>.<parameter> | Local rule | Definition of a local rule |
rule.domainsplitting.<name>.<parameter> | Local domain splitting rule | Definition of a domain splitting rule |
domainsplitting.<name>.<parameter> | Global domain splitting setting | Initialization for domain splitting - see chapter Concept - URL Handling (valid to 7.7)#Domain Splitting. |
The following parameters can be used globally and locally as stated in the example. The settings hideDefaultApplicationID
and domainsplitExpandPattern
have been removed. The following has been newly introduced: shortpathpattern
. Scopes can be rules.
or rule.<name>.
.
Setting = Default Value | Description |
---|---|
<scope>.clear = true/false | Removes all previously loaded rules, allowing to start from scratch with the current urlrewrite.properties |
<scope>.supportHttps = true/false | Perform URL Rewriting on links with protocol of type HTTPS |
<scope>.restrictToWhitelistedParameters = true/ false | Only "whitelisted" request parameters will be passed through (either defined by pipeline/start node API or configured via pipelinewhitelistparameters.properties) - introduced with 7.3.1 |
<scope>.replaceGermanUmlauts = true/false | Replaces all German umlauts in Object Path variables according to the following pattern: ö => oe, ü => ue, etc. |
<scope>.replaceSpecialCharacters = true/false | If the value is true, then the following normalization form (Normalization Form - NFKD) will be used. After the normalization step the characters have to match all ASCII characters. Otherwise they will be removed. The regex expression "[^\\p{ASCII}]" will be used. The following examples demonstrate what happens: example 1: Original: "Tĥïŝ ĩš â fůňķŷ Šťŕĭńġ" NFKD + ASCII Comparison: "This is a funky String" example 2: Original: "äöüß^§$%&買い得" NFKD + ASCII Comparison: "aou^$%&" For more details about normalizing text see https://docs.oracle.com/javase/tutorial/i18n/text/normalizerapi.html. |
<scope>.replaceSlashes = true/false | Replaces slashes with "-" |
<scope>.fullCategoryPath = true/false | Current #CategoryBO:CatalogCategoryPath:ReversePath:DynamicPath# will show the current category and all its parents (e.g., /computer101/desktops13/) |
<scope>.localizedCategoryPath = true/ false | Current #CategoryBO:CatalogCategoryPath:ReversePath:DynamicPath# will provide localized names |
<scope>.forceDomainsplittingHost = true/ false | At least one domain splitting host will be forced to be active. |
<scope>.debug = true/false | Debugging into \share\system\log\debug-<server>.log when debugging for |
<scope>.shortpathpattern = ${path} | Defining a URL pattern where the parameters (domain, group, locale, appurlid, currency) take part (e.g.: /${group}/${domain}/${locale}/${appurlid}/${currency}${path}) |
Rules are defined by using the rule.<name>.<parameter>
pattern.
# compact parameter rule.<name>.select = ${action} rule.<name>.selectMatch = ^ViewHomepage-DisplayCachedHomepage$ rule.<name>.shortPath = /start # expand parameter rule.<name>.shortPathMatch = ^/start$ rule.<name>.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage # optional parameters to overwrite global settings rule.<name>.shortpathpattern = ${path}-${group}-${domain}-${locale}-${appurlid}-${currency} rule.<name>.debug = true rule.<name>.replaceSlashes = false ...
Algorithm for compacting
The .select
part is matched against .selectMatch
. In case of success, the long URL is transformed into the .shortpath
by optionally using the .shortpathpattern
.
Algorithm for expanding
The short URL is matched against .shortPathMatch
. In case of success, the short URL is transformed into the .longRequest
.
Optional parameters
Global parameters like .debug
, .replaceSlashes
etc. can be overwritten by each rule.
Rewrite rules can be overwritten. The look-up for urlrewrite.properties files is similar to the look-up for templates and pipelines. The URL handler checks all cartridges in the order of the cartridgelist.properties to build up a stack of rules. Rules in higher-level cartridges override rules with the same names in lower-level cartridges properties files. rules.clear=true
will remove previously loaded rules.
As a default homepage rule, you may start with linking the http://
www.example.com/
URL to the ViewHomepage-DisplayCachedHomepage
pipeline.
# Compacted URL: http://www.example.com/ rule.homepage.select = ${action} rule.homepage.selectMatch = ^ViewHomepage-DisplayCachedHomepage$ rule.homepage.shortPath = / rule.homepage.shortPathMatch = ^/$ rule.homepage.longRequest = /WFS/PrimeTech-PrimeTechSpecials-Site/en_US/-/EUR/ViewHomepage-DisplayCachedHomepage
When domain splitting is not enabled, all other rules should have the following parameters stored in the URL: group, domain, locale, appurlid and currency.
# Compacted URL: http://www.example.com/sitemap-A-Z-PrimeTechSpecials-WFS-en_US-myApp-USD rule.sitemap.select = ${action}/${p.Range}/ rule.sitemap.selectMatch = ^ViewSitemap-BrowseCategoryRange/.+/$ rule.sitemap.shortPath = /sitemap-${p.Range}${d.RenderType}-${domain}-${group}-${locale}-${appurlid}-${currency} rule.sitemap.shortPathMatch = ^/sitemap-([A-Z|0-9]-[A-Z|0-9])-([\\w\\-]+)-([\\w]+)-([\\w]+)-([\\w\\-]+)-([\\w]+)$ rule.sitemap.longRequest = /$3/$2/$4/$5/$6/ViewSitemap-BrowseCategoryRange?Range=$1&RenderType=CategoryRange
Due to the latest rework, the latter rule can be simplified as follows. Therefore a global pattern is defined through the use of rules.shortpathpattern
. This global pattern contains a ${path} placeholder representing the part which rules are then matched.
# Compacted URL: http://www.example.com/sitemap-A-Z-PrimeTechSpecials-WFS-en_US-myApp-USD rules.shortpathpattern = ${path}-${domain}-${group}-${locale}-${appurlid}-${currency} ## alternately # rules.shortpathpattern = /${domain}/${group}/${locale}/${appurlid}/${currency}${path} rule.sitemap.select = ${action}/${p.Range}/ rule.sitemap.selectMatch = ^ViewSitemap-BrowseCategoryRange/.+/$ rule.sitemap.shortPath = /sitemap-${p.Range}${d.RenderType} rule.sitemap.shortPathMatch = ^/sitemap-([A-Z|0-9]-[A-Z|0-9])$ rule.sitemap.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewSitemap-BrowseCategoryRange?Range=$1&RenderType=CategoryRange
User-friendly URLs contain semantic information like the product's display name. This additional information can be located in the dictionary. The following objects are available in the standard version: ProductBO
, CategoryBO
or Pagelet
. Further objects can be added. The rule-based URL rewrite handler allows to access that information via default Intershop Object Path variables. The example below uses a custom article name that must be placed in the dictionary whenever this rule is active. A rule takes effect when selectMatch
matches the select
(ed) values.
# standard: http://..../ViewProduct-Start?SKU=SKU_1234 # rewritten: http://www.example.com/product-details/SKU_1234/car_oel_filter_green domainsplitting.rule.productdetails1.select = ${action}/${p.SKU} domainsplitting.rule.productdetails1.selectMatch = ^ViewProduct-Start/([a-zA-Z0-9\\_\\-]+)$ domainsplitting.rule.productdetails1.shortPath = /product-details/${p.SKU}/#CustomArticleName# domainsplitting.rule.productdetails1.shortPathMatch = ^/product-details/([a-zA-Z0-9\\_\\-]+)/([a-zA-Z0-9\\_\\-]+)$ domainsplitting.rule.productdetails1.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewProduct-Start?SKU=$1
Alternatively, semantic information can be added as a query parameter (${p.param_name}). This approach comes with less flexibility for the rules and can lead to complicated (not rewritten) URLs and a lower cache performance in the production environment. Irrespective of the chosen approach, the developer who introduces new business logic and new URLs should always take care of providing semantic information for URL rewriting.
# standard: http://..../ViewProduct-Start?SKU=SKU_1234 # rewritten: http://www.example.com/product-details/SKU_1234 domainsplitting.rule.productdetails2.select = ${action}/${p.SKU}/ domainsplitting.rule.productdetails2.selectMatch = ^ViewProduct-Start/([a-zA-Z0-9\\_\\-]+)/$ domainsplitting.rule.productdetails2.shortPath = /product-details/${p.SKU} domainsplitting.rule.productdetails2.shortPathMatch = ^/product-details/([a-zA-Z0-9\\_\\-]+)$ domainsplitting.rule.productdetails2.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewProduct-Start?SKU=$1
Since version Enfinity Suite 6.6, categories provide additional methods for URL rewriting.
Object path expression | Description/Example |
---|---|
#CategoryBO:CatalogCategoryPath:ReversePath: FullPath# | full category path, e.g., http:<hostname>/camera-camcorder/memory/mms |
#CategoryBO:CatalogCategoryPath:ReversePath: LastCategoryPath# | Parent category path, e.g., http:<hostname>/camera-camcorder/mms |
#CategoryBO:CatalogCategoryPath:ReversePath: DynamicPath# | DynamicPath is a placeholder which is expanded by the RewriteHandler to |
#ProductBO: LCName# | Retrieve a lower case converted product display name |
#CategoryBO: LCDisplayName# | Retrieve a lower case converted category display name |
Basically, the domain splitting feature allows for host name parameter mapping. Domain splitting rules assume that parameters like group, domain, locale, appurlid and currency are fixed to a given hostname. Therefore, certain standard parameters can be applied whenever the hostname matches www.example.com
in the following example.
domainsplitting.example_us.host = www.example.com domainsplitting.example_us.currency = USD domainsplitting.example_us.appurlid = - domainsplitting.example_us.locale = en_US domainsplitting.example_us.domain = PrimeTech-PrimeTechSpecials-Site domainsplitting.example_us.group = WFS
Host name parameter mappings should be located centrally in /share/system/config/cluster/urlrewrite.properties (no reloading supported). For testing purposes, they can also be defined in cartridge-specific urlrewrite.properties files (reloading supported).
If there is another instance of example located in Germany, for example, the following additional domain splitting preferences can be set up:
domainsplitting.example_de.host = www.example.de (or *de*.example.com) domainsplitting.example_de.currency = EUR domainsplitting.example_de.appurlid = - domainsplitting.example_de.locale = de_DE domainsplitting.example_de.domain = PrimeTech-PrimeTechSpecials-Site domainsplitting.example_de.group = WFS
The resulting URL rewriting rules have domainsplitting.
as prefix and are much more readable. Standard parameters can be accessed using ${parameter_name
}.
domainsplitting.rule.register.select = ${action} domainsplitting.rule.register.selectMatch = ^ViewUserAccount-ShowLogin$ domainsplitting.rule.register.shortPath = /register domainsplitting.rule.register.shortPathMatch = ^/register$ domainsplitting.rule.register.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewUserAccount-ShowLogin
This way, URLs can be shortened drastically by hiding information via DNS name. This naming strategy is search engine friendly: human readability is improved and higher ratings in search engines can be expected.
The standard domain splitting has been enhanced to support three new features:
It is possible to define multiple host names for one domain splitting set. This way, multiple host names can share the same settings, which reduces the number of domain splitting configurations. The different host names must be separated by spaces.
domainsplitting.host1.host=www.example.com test-example dev-example.local
Another improvement is the definition of host names which now may include port numbers. This was not possible before with URL rewriting:
domainsplitting.host1.host=www.example.com:81 www.example.com:444
For backward compatibility, the following plain host name still works by ignoring the actual port:
domainsplitting.host1.host=127.0.0.1
Currently, the default rewritten URLs for the inTRONICS channel may have the following style:
[protocol]://[hostname][:port]/contact-${domain}-${group}-${locale}-${appurlid}-${currency}
Here, the suffix is always the same:
-${domain}-${group}-${locale}-${appurlid}-${currency}
and the actual path segment is:
/contact
This feature aims at declaring a master pattern for each path section of a URL like, for example:
rules.shortpathpattern=${path}-${domain}-${group}-${locale}-${appurlid}-${currency}
Following this master pattern, all default parameters (e.g., domain, group, currency, ...) can be extracted initially. After this, the existing standard URL rewriting can be performed on the extracted path section:
/contact
All placeholders have a default regular expression set as shown in the table below:
placeholder | Regular Expression |
---|---|
domain | [\w-]+ |
group | [\w]+ |
locale | [a-z]{2}_[A-Z]{2}|[a-z]{2} |
appurlid | [\w-]+ |
currency | [\w]+ |
path | .* |
They can be overridden by following the pattern:
# default pattern: ${placeholdername} # override pattern: ${placeholdername:(regex)} # limiting a placeholder to certain values (e.g. en_US, de_DE or fr_FR) domainsplitting.host1.shortpathpattern=${locale:(en_US|de_DE|fr_FR)} # path must start with a leading slash (/) - recommended for fallback pattern domainsplitting.host1.shortpathpattern=${path:(\\/.*)} # currency must contain exactly 3 characters, _ or digits domainsplitting.host1.shortpathpattern=${currency:([A-Z]{3})} # group contains up to 3 characters, _ or digits domainsplitting.host1.shortpathpattern=${group:([\\w]{,3})}
When a rule is compacted or expanded, a look-up for the short path pattern is performed. This look-up uses the first found shortpathpattern
to match.
The following sections list these levels in the order of their look-up priority:
1) Local- for each rule individually
A rule may provide its own shortpathpattern.
rule.home.select = ${action} rule.home.selectMatch = ^ViewHomepage-DisplayCachedHomepage$ rule.home.shortPath = /index rule.home.shortPathMatch = ^/index$ rule.home.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage rule.home.shortpathpattern = /${locale}${path}-${domain}-${group}-${appurlid}-${currency}
2) Domain specific- specific for given host names
Definition of a short path pattern being active when domain splitting settings match. Here, the short path pattern needs to provide the parameters that are missing in the current domain splitting configuration (e.g., locale).
domainsplitting.host_1.host = www.example.de local.test-example.de domainsplitting.host_1.shortpathpattern = /${locale}${path} domainsplitting.host_1.currency = USD domainsplitting.host_1.appurlid = - ### definition of locale is not necessary! - it is defined through the shortpathpattern ### domainsplitting.host_1.locale = en_US domainsplitting.host_1.domain = inSPIRED-inTRONICS-Site domainsplitting.host_1.group = WFS
3) Global- applying for all rules
This pattern is used when none of the above (domain specific or local) shortpathpattern
is found:
# global URL pattern as ultimate fallback if no other shortpathpattern are available rules.shortpathpattern = ${path}-${domain}-${group}-${locale}-${appurlid}-${currency} # example rule rule.home.select = ${action} rule.home.selectMatch = ^ViewHomepage-DisplayCachedHomepage$ rule.home.shortPath = /index rule.home.shortPathMatch = ^/index$ rule.home.longRequest = /${group}/${domain}/${locale}/${appurlid}/${currency}/ViewHomepage-DisplayCachedHomepage
The global shortpathpattern
needs to provide the following parameters: domain, group, locale, appurlid
(if different from -), and currency
, whereas a domain-specific shortpathpattern
may provide only the missing parameters.
A rewritten URL, following the short path pattern /${locale}/${appurlid}${path
}, may lead to a URL like this:
http:/example.ch/de_CH/mobileapp/contact
This URL is not SEO-compliant, since the country code is included twice (ch
is part of the host name and part of the URL path) and the mobile application could be abbreviated to "mobile". A better way to present this information would be the following URL:
http:/example.ch/de/mobile/contact
To this end, it is possible to provide alternative replacements for locale
, appurlid
and currency
. The mappings can be defined individually for each domain splitting. An example is listed in the following (see mapping comments).
# server for switzerland domainsplitting.host_1.host = example.ch # fixed currency domainsplitting.host_1.currency = CHF # fixed server group domainsplitting.host_1.group = WFS # fixed site domainsplitting.host_1.domain = inSPIRED-inTRONICS-Site # mappings for different apps domainsplitting.host_1.appurlid.1.value = mobileapp domainsplitting.host_1.appurlid.1.replacement = mobile domainsplitting.host_1.appurlid.2.value = tabletapp domainsplitting.host_1.appurlid.2.replacement = tablet # mappings for different locales in switzerland domainsplitting.host_1.locale.1.value = de_CH domainsplitting.host_1.locale.1.replacement = de domainsplitting.host_1.locale.2.value = it_CH domainsplitting.host_1.locale.2.replacement = it domainsplitting.host_1.locale.3.value = fr_CH domainsplitting.host_1.locale.3.replacement = fr # the new introduced shortpathpattern domainsplitting.host_1.shortpathpattern = /${locale}/${appurlid}${PATH}
Using these configuration options, the following rewritten URLs are configurable:
http:/example.ch/de/mobile/contact http:/example.ch/it/tablet/contact http:/example.ch/fr/mobile/contact
There is a need to have storefront links that reference categories, products, pagelet entry points (CMS pages), pipelines or just external links. Therefore a simple-to-use syntax was defined and is recognized inside content created with the TinyMCE text editor. The syntax of standard URLs is used whereby each link has a specific protocol set. So the following can be achieved:
Text written with the TinyMCE: "... visit our <a href="pipeline://ViewContact-Start?ref=homepage">Contact page</a> for directions."
will convert links with a custom protocol (e.g., pipeline, product, category, page,..) into:
URL Rewriting disabled: "... visit our <a href="http://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ViewContact-Start?ref=homepage">Contact page</a> for directions."
URL Rewriting enabled: "... visit our <a href="http://www.example.com/contact?ref=homepage">Contact page</a> for directions."
To give a short overview, the custom links currently available are described in the table below.
Syntax | Example | Link |
---|---|---|
http://<host>(/<path>) | http://www.external.com | http://<host>(/<path>) |
https://<host>(/<path>) | https://www.external.com | https://<host>(/<path>) |
page://<pageid> | page://systempage.homepage.pagelet2-Page | Dictionary: #PageletEntryPoint# |
product://<SKU>(@<Domainname>) | product://12345678 product://12345678@PrimeTech-Computers | Dictionary: #ProductBO# |
category://<CatalogCategoryID> | category://PCSystems@PrimeTech-Computers | Dictionary: #CategoryBO URL( Action("ViewStandardCatalog-Browse"), Parameter("CategoryName",<SKU>), Parameter("CatalogID")) |
pipeline://<pipelename-startnode> | pipeline://ViewContact-Info | URL( Action("ViewContact-Info")) |
image://<site-name/subfolder/file-name.extension> Available since Intershop 7.7 | image://inSPIRED-inTRONICS-b2c-responsive /teaser/home_teaser_1.jpg | creates a static URL |
In order to perform proper URL rewriting, a custom link will enrich the dictionary with objects like CategoryBO
, ProductBO
or PageletEntryPoint
(see table above). These dictionary entries can be referenced in rewriting rules (see excerpts from the urlrewriting.properties below).
rule.cat53.select = ${action}/#CategoryBO:Name#/ rule.cat53.selectMatch = ^ViewStandardCatalog-Browse/.+/$ rule.cat53.shortPath = /#CategoryBO:CatalogCategoryPath:ReversePath:DynamicPath#${d.CategoryName}${d.CatalogID}${d.CatalogCategoryID} .. rule.psku3.select = ${action}/#ProductBO#/ rule.psku3.selectMatch = ^ViewProduct-Start/.+/$ rule.psku3.shortPath = /#ProductBO:Name#-zid#ProductBO:ID# .. rule.page99-page.select = ${action}/#PageletEntryPoint:DisplayName#/ rule.page99-page.selectMatch = ^ViewContent-Start/.+$ rule.page99-page.shortPath = /#PageletEntryPoint:DisplayName#-cms-${p.PageletEntryPointID}
On ISML level the feature can be utilized with the IS modules ISLink
and ISHtmlPrint
as stated below:
<ISSet name="mylink" value="category://PCSystems@PrimeTech-Computers"> <!--- ISLink prints out a single link ---> <ISLink link="#mylink#"> <!--- ISHtmlPrint prints out a texts with replaced links inside ---> <ISHtmlPrint value="#'My custom link: '+mylink+' was just shown'#">
Since a custom link represents a standard URL, you are able to append parameters and anchor tags (e.g., category://PCSystems@PrimeTech-Computers?ref=summersale#specialconditions
).
The protocol of the generated URLs of a custom link can be forced to https/http by adding the parameter ?ssl=true/false
(e.g., product://12345678?ssl=true
).
Intershop 7.7 - The localization of the URLs of a custom link can be achieved by appending the parameter ?localeId=<localization-id>
(e.g.,
product://12345678?localeId=de_DE
).
The custom link rewriting is configurable via the Component Framework and must implement the StorefrontLinkRenderer
interface.
Creating or configuring custom links is described in Cookbook - URL Handling (valid to 7.7).
Intershop 7.9 - To define the URLs destination locale, site and currency, add one or more of the following parameters: ?x-locale=<localization-id>&x-site=<site-name>&x-currency=<currency-mnemonic> (e.g., product://12345678?x-locale=de_DE&x-site=inSPIRED-inTRONICS-Site&x-currency=USD).
Parameter whitelisting has been introduced to improve the page cache hit ratio in situations where unnecessary request parameters (from the start nodes' point of view) hit the Web Adapter and enforce the application server to render identical pages several times.
There are now two ways to enforce parameter whitelisting for pipeline start nodes:
To turn on the parameter whitelisting, check the urlrewrite.properties for the following setting:
# enforce whitelisted parameters # 1. defined within pipelinewhitelistparameters.properties # 2. setup for the pipeline startnode # This will remove unnecessary URLquery parameters from the request to allow the page cache to work properly # rules.restrictToWhitelistedParameters = true
Configure the valid parameters for the start nodes for which the feature should be used.
Configure the mandatory and optional paramaters of your start nodes in the file pipelinewhitelistparameters.properties according to the following example:
###################################################################################################################### ## ## Config file that lists optional & mandatory parameters for pipeline startnodes. ## (used in PipelineWhitelistParameterProvider - which currently only used for rewritten URLs) ## ## syntax: ## pipelinewhitelistparameter.<Pipeline>-<StartNode>.parameters.[mandatory|optional] = <parametername1>[/<parametertype1>], <parametername2>[/<parametertype2>], ... ## ## example: ## pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String ## pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.optional = Param3/java.lang.String, Param4/java.lang.String ## ###################################################################################################################### pipelinewhitelistparameter.Whitelist_test-StrictMandatoryParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParams.parameters.optional = Param3/java.lang.String, Param4/java.lang.String pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParamsIncludingArrays.parameters.mandatory = Param1/java.lang.String, Param2/java.lang.String[] pipelinewhitelistparameter.Whitelist_test-StrictMandatoryAndOptionalParamsIncludingArrays.parameters.optional = Param3/java.lang.String, Param4/java.lang.String[]
You can either use the cluster wide configuration file in <eserver>/share/system/config/cluster/pipelinewhitelistparameters.properties or - in case it has to be app-specific or domain-specific - in one of your project cartridges: <cartridge>/staticfiles/cartridge/config/pipelinewhitelistparameters.properties.
In case of an error, the restriction of whitelisted parameters does not prevent the request from being processed. That is, if a problem occurs, it will only be visible in the warning or error log of the server.
There are two possible errors:
The type of the parameter is set to a type that is not compatible with the passed request parameter (e.g., the parameter type is java.lang.Integer
).
Precondition:
Pipeline parameter type checking is activated via the property intershop.pipelines.strict.CheckParameterTypes
(default location: appserver.properties, default value: false
) which is set to true
and the value passed through the request is a string that cannot be converted to an integer, e.g., text
).
# performs type checking on the required and # optional keys of a strict subpipeline intershop.pipelines.strict.CheckParameterTypes=true
Result:
A parameter that is marked as mandatory is not part of the request.
Result:
Web Adapter: Configure the trace option to directly visualize the effect of whitelisted parameters.
$ vim /eserver1/share/system/config/cluster/webadapter.properties
############################################################################ ## Tracing and Control ## ## Set a 'simple, short and unique enough' command prefix to enable the ## feature. In production systems, restrict access. Like: ## <eserver>/httpd/conf/extra/httpd-webadapter.conf: ## <LocationMatch ;wa_> ## Order Allow,Deny ## Allow from 10.0.0.0/8 ## </LocationMatch> ## ## When enabled, see the built-in help for more details ## http://.../INTERSHOP/web/;wa_help ctl.commandPrefix = wa_
Call the start node that whitelisted parameters have been configured for using the "trace option":
http://localhost/Cameras-Camcorders/1421-PrimeTechSpecials-WFS-en_US-USD;wa_trace?dummy_parameter
Alternatively, you can use wa_help
to get an overview of the Web Adapter trace option:
http://localhost/Cameras-Camcorders/;wa_help;wa_trace
The different ways of compacting and expanding URLs are visualized in the following two sequence charts:
The following diagram shows the algorithm performed inside the rule class.
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.