Chapter 24. Site Redirection

⁠Chapter 24. Site Redirection

GateIn Portal includes a mechanism to redirect user to a different site within the portal based on the characteristics of their browser. This is especially useful for redirecting users to a mobile optimized site if you detect they are accessing the portal from a mobile device.

Redirections can be based on various criteria:

The user agent string of the browser accessing the site
Any properties which can be determined via javascript. This can include things like screen size, pixel density and if the device supports touch or not.

We also include options to map the nodes between one site and another when performing the redirect. This allows for greater control over what page within the site a user will end up on when a redirect is performed.

The following sections will briefly explain how to configure and setup the service using xml the configuration files.

For details on how to configure site redirects using the administration user interface, see topic Manage Site Redirections in User Guide.

Note

Redirects are only performed once for a user and stored in a cookie. The site redirect service will always use the value stored in the cookie regardless if the redirect service configuration has changed. This allows for users to specify their own preferences without being redirected to their non-preferred site when the redirection rules change. For costly browser based property detection, this also means that this check is only performed once for a user and not on each subsequent access.

Report a bug

⁠24.1. Configuring Site Redirections in XML

All of the XML configuration options to add a redirectable, or alternative site is done in the portal.xml file for that particular site.

Note

By default, the portal.xml configuration file is only read the first time the portal is ever started. To make changes after the portal has already been started, follow the directions in the Data Import Strategy chapter of the Development Guide.

Report a bug

⁠24.1.1. Adding a Redirectable Site

To add the site mobile as an alternative to the classic site you would modify the portal.xml file for the 'classic' site to include the following:

⁠

Example 24.1. Adding a Redirectable Site

<portal-redirects>
    <portal-redirect>
      <redirect-site>mobile</redirect-site> <!-- (1) -->
      <name>Mobile</name> <!-- (2) -->
      <enabled>true</enabled> <!-- (3) -->
    </portal-redirect>
</portal-redirects>

The name of the site to redirect to
The name given to the redirect
If the redirect should currently be enabled or not

Now when accessing the classic site you should notice a link at the bottom to the mobile site. If the user clicks this link, they will be redirected to that site and their preference for the alternative site will be stored. This means the next time the user tries to access the classic site they will automatically be redirected to the mobile site instead.

Note

This only creates a redirection link between already existing sites. You will still need to create the sites manually.

Note

The above steps only create a one way link. If the user also wants to make the classic site an alternative for the mobile site they will have to configure the portal.xml for the mobile site. It is highly recommended to also configure the redirect on the other site to allow the user to return to the original size as well as to set their preference to the original site.

Report a bug

⁠24.2. Automatic Redirection Based on User Agent String

The example in Section 24.1.1, “Adding a Redirectable Site” describes how to add an option for a redirect, however user intervention is required to specify which site to display. The site redirection service can be configured to redirect a user automatically from one site to another. This can be based on either the user agent string of the clients browser or through a device detection page which can gather any data which can be gathered through javascript.

When a website is accessed, the browser normally sends a user agent string which describes in part the type and version of the browser used. Automatic redirects can be configured based on the values contained within this string, which enhances the user experience when viewing the portal site on mobile devices.

An example configuration which will preform a redirect if the user agent string contains the case-insensitive string "foo" or the case-sensitive string "Bar" and does not contain the case-sensitive string "baz" :

⁠

Example 24.2. Example Redirect Based on User Agent Strings

<portal-redirects>
    <portal-redirect>
      <redirect-site>test</redirect-site>
      <name>Test</name>
      <enabled>true</enabled>
      <conditions>
        <condition>
          <name>Test Condition</name> <!-- (1) -->
          <user-agent>
            <contains>(?i)foo</contains> <!-- (2) -->
            <contains>Bar</contains> <!-- (2) -->
            <does-not-contain>baz</does-not-contain> <!-- (3) -->
          </user-agent>
       </condition>
      </conditions>
    </portal-redirect>
  </portal-redirects>

The name of the redirect condition
A list of strings to check if they exist within the user agent
A string to make sure is not within the user agent string

The condition is considered to pass if any of the contains options is matched and if none of the does-not-contain options are matched.

Note

The format of the strings is the Java Regex Pattern format. This allows for powerful pattern matching capabilities. Please see the java regex documentations for more details.

Report a bug

⁠24.3. Automatic Redirection Based on Device Properties

In some rare cases, using user agent strings may not be enough. You may need to determine some characteristics retrieve from the user's browser itself. The way we can do this is to send the user to another page first, run some javascript to gather some information and return this to the redirection service. This allows for some more powerful detection and redirection, but at the cost of extra complexity and performance degradation.

Note

It is strongly recommended to use user agent based detection whenever possible. Redirection based on device properties should be avoided if possible due to performance reasons.

Report a bug

⁠24.3.1. The Device Detection Page

The jsp page which does the detection is located:

gatein.ear/portal.war/device/detection.jsp

By default this page only detects a couple of simple options like screen width and height. To add more options, this page can be modified and calls to the javascript method addParameter() will make new options and values available to the service.

A simple configuration to detect that the touch.enabled property specified in the detection.jsp file returned the value true .

Report a bug

⁠24.3.2. Device Properties Based Redirection XML Configuration

⁠

Example 24.3. Example Redirection Based on Device Properties

	<portal-redirects>
    <portal-redirect>
      <redirect-site>test</redirect-site>
      <name>Test</name>
      <enabled>true</enabled>
      <conditions>
        <condition>
          <name>Test Condition</name>
          <user-agent>
            <contains>.*</contains> <!-- (1) -->
          </user-agent>
          <device-properties>
          	<device-property>
          		<property-name>touch.enabled</property-name> <!-- (2) -->
              <equals>true</equals> <!-- (3) -->
            </device-property>
          </device-properties>
        </condition>
      </conditions>
    </portal-redirect>
  </portal-redirects>

Java Regex Pattern that specifies that any user agent string will work.
Specifies the name of the property retrieved from the detection page to check against.
Specifies the condition to check this property. The options include: equals, greater-than, less-than, and matches (which uses Java Pattern Regex format).

Multiple options can be used against a single device property. They must all match to satisfy the condition. This allows for detecting a value within a range by using both greater-than and less-than options.

⁠

Example 24.4. Multiple Property Options

This example shows how user agent string and device property detection can be used together to match any user agent string.

If multiple device-property options are used, then they must all match to satisfy the condition.

<condition>
  <name>Test Condition</name>
  <user-agent>
    <contains>.*</contains>
  </user-agent>
  <device-properties>
    <device-property>
      <property-name>screen.width</property-name>
      <greater-than>320</greater-than>
      <less-than>1024</less-than>
    </device-property>
  </device-properties>
</condition>

An alternative configuration to what is described in Example 24.4, “Multiple Property Options” is to restrict based on the user agent string. In this scenario, the service will only ever redirect the user to the device detection page if the user agent string values pass. Narrowing the user agent string is strongly advised to prevent unnecessary redirects to the device detection page.

Report a bug

⁠24.3.3. Multiple Redirect Conditions

Multiple redirect conditions can be specified. The conditions are checked sequentially and perform the redirect when it encounters a condition which passes.

For example, the following will perform the redirect if the user agent string contains the string "foo" . If the user agent string does not contain "foo" it will check if it contains "bar" and the browser detection pare returns a touch.enabled property of true . If neither of these conditions pass, the redirect will not happen and the user's preference will be set to the original site.

⁠

Example 24.5. Multiple Redirect Conditions Example

<conditions>
  <condition>
    <name>Check Foo</name>
    <user-agent>
      <contains>foo</contains>
    </user-agent>
  </condition>
  <condition>
    <name>Check Touch</name>
    <user-agent>
      <contains>bar</contains>
    </user-agent>
    <device-properties>
      <device-property>
        <property-name>touch.enabled</property-name>
        <equals>true</equals>
      </device-property>
    </device-properties>
  </condition>
</conditions>

Report a bug

⁠24.4. Mapping Page Nodes In Redirects

When redirecting between sites, the user is actually redirected from one page node on one site to a node on another site. There are a number of configuration options available to handle node redirects.

Report a bug

⁠24.4.1. Explicit Node Mappings

The Administrator can configure explicit node mappings between the original site and the redirect site. Node mappings are always evaluated first when performing a redirect.

For example, if a redirect between classic and mobile sites is required, the http://localhost:8080/portal/classic/home/pageA URL could get redirected to the http://localhost:8080/portal/mobile/pageB URL.

Report a bug

⁠24.4.2. Node Name Matching

Node name matching is enabled by default, but can be disabled if required.

If the node is not specified in the node mappings, then the redirect can be configured to try and match the nodes from the original site to a node of the same path on the redirect site.

If a redirect is configured between the classic and mobile sites and the user tries to access http://localhost:8080/portal/classic/home/pageXYZ" and the node /home/pageXYZ exists on the mobile site, the user is redirected to http://localhost:8080/portal/classic/mobile/pageXYZ". If the node /home/pageXYZ does not exist on the redirect site, then the service will evaluate the unresolved node settings to determine where the redirect should go.

Report a bug

⁠24.5. Resolving Unresolved Nodes

If the node is not listed in the node mappings, and the node name mappings could not resolve the node, then the node is considered currently unresolved. Using the <unresolved-nodes> XML element, the service can be configured to handle unresolved nodes in a variety of ways.

REDIRECT - Redirect Anyway: If the node is not resolved, perform the redirect and use the node path from the original site.
For example, if a redirect is to occur between classic and mobile and the user accesses http://localhost:8080/portal/classic/home/pageABC but pageABC does not exist on the redirect site, the user will still be redirected to http://localhost:8080/portal/mobile/home/pageABC . This will use the portal's node resolving configuration, which by default will resolve to the next available node in the path.
NO_REDIRECT - Abort the Redirect: If the node does not exist on the redirect site, the redirect will not take place and the user will continue on to the original URI.
ROOT - Redirect to the Sites Root: If the node does not exist on the redirect site, the user is redirected to the root of the redirect site.
For example, with a redirect between classic and mobile if the node /home/PageA/PageB does not exist on the redirect site, the user is redirected to http://localhost:8080/portal/mobile even if /home/PageA exists on the mobile site.
COMMON_ANCESTOR_NAME_MATCH - Redirect Based on a Common Ancestor Node: This option is similar to the REDIRECT option, and behaves the same way if the portal is using the default node resolver.
For example, if the node on the original site is /home/PageA/PageB this option will first check if /home/PageA/PageB exists on the redirect site, then /home/PageA , then /home and will finally resolve to the root of the redirect site if no match can be found.

⁠

Example 24.6. Node Mapping XML Example


<portal-redirect>
  <redirect-site>mobile</redirect-site>
  <name>Mobile</name>
  <enabled>true</enabled>
  <conditions>
    <!-- Irrelevant content removed for readability -->
  </conditions>
  <node-mapping>
    <node-map> <!-- (1) -->
      <origin-node>home</origin-node>
      <redirect-node>mobileHome</redirect-node>
    </node-map>
    <node-map> <!-- (2) -->
      <origin-node>foo</origin-node>
      <redirect-node>bar</redirect-node>
    </node-map>
    <use-node-name-mapping>true</user-node-name-mapping> <!-- (3) -->
    <unresolved-nodes>NO_REDIRECT</unresolved-nodes> <!-- (4) -->
  <node-mapping>
</portal-redirect>

/home on the original site will always be resolved to /mobileHome on the redirect site
/foo on the original site will always be resolved to /bar on the redirect site
Node name matching will be attempted.
If the origin node is not resolved from either the mapping or the name matching, then no redirect will occur.

Report a bug

⁠24.6. Disabling Redirect Handler

The Site Redirection service can impact performance because it imposes additional overheads on the server when processing client requests. If this service is not required, it can be disabled using the following methods.

Removing the redirect portlet from the site layout.

Removing or commenting the following code from JPP_HOME/standalone/configuration/gatein/controller.xml


  	
<!-- The portal redirect handler -->
<route-param qname="gtn:handler">
  <value>siteRedirect</value>
</route-param>

Report a bug