Javascript In Thl

THL Toolbox > Developers' Zone > Web Development > Javascript in THL

Javascript in THL

Contributor(s): Than Grove

Like most sites these days, THL relies heavily on Javascript (JS). In particular, we have designed our site around the external link: JQuery Javascript Library. The main JS files are found at the root level in the "/global/js" folder. There, the latest version of Jquery is included renamed as jquery-latest.js. (It is not a symlink because symlinks cannot work on Windows localhosts.) The most common and ubiquitous JS scripts are all combined into a single call using a PHP script at /global/php/combineJS.php. Furthermore, while on Development (and your localhost if you run one), the scripts are unpacked in full, editable form, on Staging and Development, they are minimized to speed up loading time. These three topics–Updating Jquery, Adding a JS to the CombineJS Call, and Minimizing JS for Staging and Production–are discussed below.

Updating JQuery

As of this writing (Dec. 2010), Development, Staging, and Production all use the latest version of JQuery, version 1.4.4. You can determine the version presently being used by looking at the script on the server, such as external link: external link: http://dev.thlib.org/global/js/jquery-latest.js. The top of that file will look like:

/*!
 * jQuery JavaScript Library v1.4.4
 * external link: http://jquery.com/
 *

This tells you the version number is 1.4.4.

To update to a newer version:

  1. Download the latest version to your computer in a folder different from /global/js.
  2. Rename it as jquery-latest.js
  3. In the /global/js/ folder, right click on jquery-latest from the Tortoise SVN menu choose rename and rename it with the version number as jquery-1.4.4.js. (Note: the command in SVN to rename is "svn move old-name new-name".)
  4. Copy the new jquery-latest.js to the /global/js/ and commit it as a new version.

Please note that THL uses many JQuery-based plugins and some of these may break when JQuery is updated. So new versions of JQuery need to be tested thoroughly.

Minimizing Global Javascripts

While the scripts on development are not compressed in any way because they are for development purposes and can change frequently, all the major javascripts in the /global/js folder on staging and production need to be minimized. Script are minimized using the YUI compressor (version 2.4.2, as of this writing). There is a script set up for compressing the scripts into a minimized format in the wwwglobaljsminimize folder on staging.

In the wwwglobaljsminimize folder there is a sub-folder called fromDev. All scripts to be compressed should be copied from the development wwwglobaljs folder to this folder at wwwglobaljsminimizefromDev folder. To compress a javascript one must open a command-line window in that folder. In Windows 7, this can be achieved by right-clicking on the folder and choosing File Menu Options --> Command Line. Then, type:

MinimizeTHLJS.bat {name of script without .js extension}

As for instance,

MinimizeTHLJS.bat jquery.thdl

or

MinimizeTHLJS.bat fn

The minimized version of the script will be in /global/js/minimize/toStaging folder. It will have the name of the original script except with ".min" appended before the ".js" extension (e.g., fn.min.js). It should be Committed to SVN there but also copied to the Staging /global/js folder.

If the command MinimizeTHLJS.bat is run without giving it a particular script, then a predefined list of scripts will be all compressed. The list of standard scripts to compress, which is found in the /global/js/minimize/thl-js-files.dat file, is:

  1. accordion
  2. app_plug
  3. book
  4. class_external
  5. class_wikiloader
  6. cookies
  7. crypt
  8. fn
  9. jquery.history1.0beta
  10. jquery.checkbox
  11. jquery.menus
  12. jquery.menus.utilities
  13. jquery.position
  14. jquery.thdl
  15. jquery.thl.popup
  16. jquery.toXML
  17. jquery.watermarkinput
  18. map
  19. thl-tt-plugin

These files must be found in the wwwglobaljsminimizefromDev folder. So the latest files from Dev must be copied there.

Combining Javascripts into a Single file

To speed up loading, the major javascripts are combined into a single file using a PHP script. So, the generic call for THL javascripts in a typical THL page is:

<script type="text/javascript" src="/global/php/combineJS.php"></script>

What this script does is to read a predefined list of javascripts from the /global/js folder and combine them into a single output, which speeds up loading. The list of scripts that are automatically included within all THL pages is found in the /global/php/combineJS.php script. At present (Feb. 2011), it is:

  1. cookies
  2. jquery-latest
  3. accordion
  4. fn
  5. jquery.history1.0beta
  6. class_external
  7. class_wikiloader
  8. jquery.thdl
  9. jquery.checkbox
  10. jquery.watermarkinput
  11. jquery.menus.utilities
  12. jquery.menus
  13. jquery.position
  14. jquery.toXML
  15. jquery-ui-themeless.min
  16. app_plug
  17. jqModal
  18. jquery.thl.popup
  19. jquery.viewport.min
  20. thl-tt-plugin

To add a new script to the output, one must add its name without the ".js" extension to this file.

Note: Because Staging and Production use minimized versions of the JS, the list of files in the combineJS.php script on those servers is slightly different, since all the names content the ".min" suffix. So, when adding a new script it must be added differently on Development and Staging, and then the Staging version pushed to Production.

The call to the combineJS.php script is written into THL pages by the class_thl_integration.php file.

Provided for unrestricted use by the external link: Tibetan and Himalayan Library