Portal Redirection Configuration

Overview

The portal can be configured to redirect from one site to another based on the user agent (ie browser) of the user accessing the site. This can be useful to perform a redirect to a mobile optomized site if a mobile device is accessing a non mobile optimized site.

Currently the configuration for site redirection is limited to the portal.xml configuration files.

Adding an Alternative Site

To add an alternative site for a particular portal, the following will have to be added to the portal.xml for that particular site:

For example from portal.war/WEB-INF/conf/portal/portal/mobile/portal.xml

  <portal-redirects>
    <portal-redirect>
      <redirect-site>classic</redirect-site> (1)
      <name>Desktop</name> (2)
      <enabled>true</enabled> (3)
    </portal-redirect>
  </portal-redirects>

1) The name of the alternative site

2) A name to give this redirect

3) If this redirect should currently be currently enabled or not

Adding Conditions to Perform a Redirect

Conditions can be added to an alternative site so that a user will automatically be redirected to another site instead. There are two main types of conditions which can be used: user agent string based and device characteristic based.

NOTE: due to issue https://issues.jboss.org/browse/GTNPORTAL-2529 device characteristic based redirects will not function with 3.4.0.M01.

Configuring User Agent String Based Redirects

A user's browsers will usually send a header to each page it access with information about the browser. This information can be easily accessed by the portal and used to perform redirects based. We can base this on if a user agent string contains or does not contain a pattern.

For example from portal.war/WEB-INF/conf/portal/portal/classic/portal.xml

  <portal-redirects>
    <portal-redirect>
      <redirect-site>mobile</redirect-site>
      <name>Mobile</name>
      <enabled>true</enabled>
      <conditions>
        <condition>
          <name>Default Mobile Condition</name> (1)
          <user-agent>
            <!-- multiple contains means _any_ of the contains must be matched -->
            <contains>(?i)i(phone|pad|pod)</contains> (2)
            <contains>(?i)mobile</contains> (2)
            <contains>(?i)android</contains> (2)
            <contains>(?)phone</contains> (2)
            <contains>(?i)tablet</contains> (2)
            <does-not-contain>foobar</does-not-contain> (3)
          </user-agent>
       </condition>
      </conditions>
      <node-mapping>
        <use-node-name-matching>true</use-node-name-matching>
      </node-mapping>
    </portal-redirect>
  </portal-redirects>

1) The name for this particular condition

2) a list of options to check if the user agent string matches

3) an option to check if the user agent string does not contain this value.

In order for this condition to pass, at least one contains must match and no does-not-contain. The checks use the Java Pattern format for regular expression checking.

Configuring Device Characteristic Based Redirects

If user agent string matching is not precise enough, we can redirect the user to a device capability test page which can use javascript to write custom tests to determine more information about the browser. Since this requires a redirection to a special page and have javascript tests run, it is slower than using user-agent based checks, for this reason user-agent based tests should be preferred.

For example, we can use this to determine things like screen resolution, pixel density or touch based events.

NOTE: due to issue https://issues.jboss.org/browse/GTNPORTAL-2529 device characteristic based redirects will not function with 3.4.0.M01.

The page which tests for this is located at portal.war/device/detection.jsp and a developer is free to add their own custom tests to this page.

Configuring a redirect based on device characteristics:

<condition>
  <name>Touch Enabled</name> (1)
  <user-agent>
    <contains>.*</contians> (2)
  </user-agent>
  <device-property>
    <property-name>touch.enabled</property-name> (3)
    <equals>true</equals> (4)
  </device-property>
</condition>

1) The name of the condition

2) Passes for all user-agents

3) The name of the property to check (see detection.jsp)

4) The condition to match it against. Options here include: greater-than, less-than, equals and matches (uses the Java Pattern Regex format). More than one option can be used here (for example, you can check a range by using both greater-than and less-than).

Configuring For both User Agent String and Device Characteristic Based Redirects

You can check for multiple redirect conditions. The order matters, and since using device characteristic based detection requires more time to perform the redirect to detection.jsp it should usually be last in the list. User Agent based checks are usually much faster and is more prefered. For example, the following will perform the redirect if the the user-agent contains 'foo', or if the device can handle touch events:

<condition>
  <name>Foo, not bar, and touch</name>
  <user-agent>
     <contians>foo</contains>
     <does-not-contain>bar</does-not-contain>
  </user-agent>
  <device-property>
    <property-name>touch.enabled</property-name>
    <equals>true</equals>
  </device-property>
</condition>

Multiple Redirect Conditions

You can check for multiple redirect conditions. The order matters, and since using device characteristic based detection requires more time to perform the redirect to detection.jsp it should usually be last in the list. User Agent based checks are usually much faster and is more prefered. For example, the following will perform the redirect if the the user-agent contains 'foo', or if the device can handle touch events:

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

Redirect Site Mapping

There are various options on how to configure the mapping between nodes on the original site and which node should be accessed on the redirect site. For example, if a user is trying to access http://portal/classic/mySite and we determine that a redirect should be performed, we need to be able to determine which node exactly the user should be redirected to on the redirect site.

The portal.xml configuration options:

<portal-redirect>
  <redirect-site>mobile</redirect-site>
  <name>Mobile</name>
  <enabled>true</enabled>
  <conditions>
    ...
  </conditions>
  <node-mapping>
    <node-map> (1)
      <origin-node>home</origin-node>
      <redirect-node>mobileHome</redirect-node>
    </node-map>
    <node-map>
      <origin-node>foo</origin-node>
      <redirect-node>bar</redirect-node>
    </node-map>
    <use-node-name-mapping>true</user-node-name-mapping> (2)
    <unresolved-nodes>NO_REDIRECT</unresolved-nodes> (3)
  <node-mapping>
</portal-redirect>

1) node-map explicitly map the nodes from one site to a node on the redirect site. Here it specifies that if the user is trying to access the home node on the original site should be redirected instead to the mobileHome on the redirect site. Explicite node mappings always take precendent over the other mapping options and will always occur, even if the node does not actually exist on the redirect site. For example here if the user tries to access http://portal/classic/home they will instead be sent to http://portal/mobile/mobileHome

2) if use-node-name-mapping is true, then if a node exists with the same name as the original redirect node, we will perform the redirect to that node. For example if the user is trying to access http://portal/classic/helloworld and http://portal/classic/helloworld exists (and there is no 'helloworld' specified in a node-map) then we will just redirect to http://portal/classic/helloworld.

If use-node-name-mapping is set to false, then we don't check a node with the same name exists on the redirect site. If that node is not specified in a node-map, then we look to the unresolved-nodes option to determine how to proceed.

3) unresolved-nodes deterines what should happen if the node is not specified in a node-map and is not resolved using use-node-name-mapping (or use-node-name-mapping is set to false). There are various options here:

REDIRECT

Perform the redirect anyways. For example, if the user is original trying to access http://portal/classic/test and http://portal/mobile/test doesn't exist, still redirect the user to http://portal/mobile/test, the portal will usually handle this as sending the user to http://portal/mobile. If the original and redirect site are very simialr, this option along with a false use-node-name-mapping is most efficient since we don't have to check if the node on the redirect site actually exists or not.

NO_REDIRECT

If we don't have a match, then don't perform the redirect. For example, if the user tries to originaly access http://portal/classic/abc and abc is not in a node-map and we don't get a match using use-node-name-mapping (or its set to false), then we don't redirect the user to http://portal/mobile/abc they will access http://portal/classic/abc as normal.

ROOT

If there is not match, then we redirect to the root of the redirect site. For example, if the user originally tried to access http://portal/classic/abc and abc is not in a node-map and we don't get a match using use-node-name-mapping (or its set to false), then we redirect to the root of the redirect site, http://portal/mobile. This is useful if the original site is not appropriate for the user agent accessing it(for example, a flash heavy classic site which would not function properly on mobile devices).

COMMON_ANCESTOR_NAME_MATCH

Tries to match ancestor nodes based on their node name. For example, if the user originally tries to access http://portal/classic/test/abc/123 and http://portal/mobile/test/abc/123 does not exist but http://portal/mobile/test/abc does exist, then the user will be redirect to http://portal/mobile/test/acb. If there are no common ancestors with matching names, the user will be redirected to the root of the redirect site.