API: Script: Redirect

Redirect Script Basics

The UCLA Mobile Web Framework provides a script that redirects "mobile" users away from one page to another.

The basic syntax for enabling such a redirect must include at minimum a URL encoded path for the GET parameter m.

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}">
</script>

A mobile user is one that is classified as such by mwf.classification.isMobile(), namely one that has a screen size (as determined by mwf.screen) less than the dimensions configured by the framework service provider in config/global.php.

Compatibility Note: In MWF 1.0-1.1, rather than using Javascript to classify the user as mobile or non-mobile, the static metadata instead provided this definition. As such, the devices classified as mobile in MWF 1.0-1.1 may vary slightly from those in MWF 1.2.

At the most basic level, the advantage to using this script, as opposed to a self-engineered one, is that it considers user agents consistently with the mobile web framework itself, and it does so for a total payload of under 2 KB, as opposed to the JS Handler, which has a much larger payload size.

The redirect script also includes other benefits such as override capabilities and domain specificity (see below).

Overriding the Redirect

Sometimes a user on a mobile device may desire to view the full site, rather than the mobile site.

The redirect script makes this kind of functionality possible through a very simple mechanism. If a user requests a page with the redirect script included, but does so with a GET parameter override_redirect=1, then the redirect script will not redirect the user.

The redirect preference may be reset to redirect to mobile by requesting a page with override_redirect=0.

Compatibility Note: In MWF 1.0-1.1, the override GET parameter was ovrrdr. For backwards compatibility, the ovrrdr parameter is still regarded as valid in MWF 1.2. However, MWF 1.0-1.1 do not accept the override_redirect parameter, as this was added in MWF 1.2.

The redirect script maintains the preference specified by the override_redirect parameter for all pages that include the script. By default, it maintains the preference for five minutes, refreshing the preference whenever the user lands on any page that also includes the redirect script.

There are three reasons an override on the redirect may stop:

• A page with assets/redirect/js.php is requested with the GET parameter override_redirect=0.
• Five minutes pass without the user visiting a page that includes assets/redirect/js.php.
• The user visits a page that uses the mobile framework, most notably the assets/js.php file.

To avoid conflict between these scripts, assets/redirect/js.php file should never be included on the same page as the framework assets/js.php file.

Domain Specificity and Expiries

In some cases, it may not make sense to override the redirect universally. For example, one application might have links to another and the user might want to be on the desktop site for the first application, but on the mobile site for the other application.

Therefore, the script allows a domain identifier specified in the script include path as the GET parameter d:

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}&d={DOMAIN}">
</script>

In this case, the override call is still the same: request sample.php?override_redirect=1 to prevent the redirect on sample.php. In this case, however, the setting will only apply to pages that include assets/redirect/js.php with the GET parameter d equal to {DOMAIN}.

For a specific domain, one may also set the expiration time on the preference to something besides five minutes via the GET parameter e. This parameter is interpreted as the number of seconds until expiration from the current time:

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}&d={DOMAIN}&e={EXPIRY_SECONDS}">
</script>

To avoid unintended global behaviors, the e parameter is not accepted without a d parameter for the domain.

This script thus provides a very powerful cross-domain way of achieving redirection and maintaining user browser preferences.