API: Script: JS Handler

ebollens edited this page Oct 4, 2011 · 11 revisions
Clone this wiki locally

Description

The JS Handler (js.php) is responsible for loading MWF Javascript functionality and related libraries. It does this through a dynamic process that considers the classification of the visitor's device and serves out scripts catered to that device. It also allows a content provider (someone using the handler) to specify additional files that should be loaded in and minified at a particular classification level. Though a PHP file, this handler identifies itself as content-type text/javascript.

Intent

To deliver framework Javascript functionality based on the classification of the user's browsing device and to minify/import additional libraries and scripts defined by the content provider, all within one requested script file.

Basic Implementation

Loading the JS Handler

The dynamic JS handler resides at:

http://{MOBILE_DOMAIN}/assets/js.php

This file can be included through a standard <script> tag as with any other JS file:

<script type="text/javascript" src="http://{MWF_INSTALLATION_ROOT}/assets/js.php"></script>

Loading Framework Libraries

In addition to the default functionality always loaded by the framework, this handler also provides a mechanism to load additional framework libraries such as Geolocation and Touch Transitions. To do this, it provides the GET parameters standard_libs and full_libs.

<script type="text/javascript" src="http://{MOBILE_DOMAIN}/assets/js.php?standard_libs=geolocation"></script>

Multiple libraries can be concatenated with a plus sign (+):

<script type="text/javascript" src="http://{MOBILE_DOMAIN}/assets/js.php?full_libs=transitions+touch_transitions"></script>

Loading and Minifying Custom Javascript

In addition to loading in the framework Javascript API, this also supports adding your own Javascript (automatically minified) to any classification level through the JS handler. In specifying a classification (basic, standard or full), the Javascript will be fetched, minified and served out to any device of that classification level or higher.

For example, to include a custom Javascript file for devices at the standard level and above:

<script src="http://{MOBILE_DOMAIN}/assets/js.php?standard={URL_ENCODED_PATH}" type="text/javascript"></script>

It is possible to include multiple custom Javascript files for devices at the same level as follows:

<script src="http://{MOBILE_DOMAIN}/assets/js.php?standard={URL_ENCODED_PATH}+{URL_ENCODED_PATH_2}" type="text/javascript"></script>

A prototype that includes files at both Javascript classification levels:

<script src="http://{MOBILE_DOMAIN}/assets/js.php?standard={URL_ENCODED_PATH}&full={URL_ENCODED_PATH_2}" type="text/javascript"></script>

While the JS Minifier provides this same sort of minification, for pages using js.php, this method is recommended as it reduces the total number of HTTP requests by doing all the custom minification within a single HTTP request.

Compatibility Note: Minification directly within the JS Handler has been available since MWF 1.1. Content providers using an instance of MWF 1.0 must instead leverage the JS Minifier.

Flags to Disable Framework Functionality

The js.php file, by default, writes several items that content providers may not desire. As such, js.php provides flags that allow individual functions to be disabled. These flags are listed below individually, but can be mixed together and in tandem with all other GET parameters.

Google Analytics

Google Analytics can also be turned off for sites with security concerns:

<script type="text/javascript" src="http://{MWF_INSTALLATION_ROOT}/assets/js.php?no_ga"></script>

It should be noted that multiple instances of Google Analytics may run at once. This means that the framework Google Analytics will not conflict with Google Analytics instances also included by a content provider. Consequently, this should only be disabled if one does not wish to allow reporting at all to the central Google Analytics instance. This will lead to the site not having any global statistics provided.

Favicon and Application Icons

By default, js.php defines both a favicon and application icons from the framework.

For instances looking to set their own favicon, it can be disabled:

<script type="text/javascript" src="http://{MWF_INSTALLATION_ROOT}/assets/js.php?no_favicon"></script>

For instances looking to set their own application icon, it too can be disabled:

<script type="text/javascript" src="http://{MWF_INSTALLATION_ROOT}/assets/js.php?no_appicon"></script>

For instances looking to disable both the favicon and application icons, they can also be disabled simultaneously through one flag:

<script type="text/javascript" src="http://{MWF_INSTALLATION_ROOT}/assets/js.php?no_icon"></script>

The no_icon flag is equivalent to a combination of both the no_favicon and no_appicon flag.