Edgewall Software

JavaScript for Trac and plugin development

JavaScript is used in Trac to add dynamics to web interface elements on the browser side:

3rd party libraries

jQuery

Trac makes heavy use of jQuery library to ease development. Access to this library contents is usually provided through the main function named $. $ as a name used for brevity and clarity. Unfortunately, other libraries may use it too and this may cause conflicts. $ in fact is just a shortcut for jQuery namespace and it is possible to use full name instead. But to avoid conflicts with other libraries $ shortcut should is turned off by switching jQuery into non-conflict mode with jQuery.noConflict() call. This is well explained in http://docs.jquery.com/Using_jQuery_with_Other_Libraries

However, you will see many blocks in Trac that use $ for jQuery. They do it in their local scope defined by nameless function (or closure):

(function($) { /* some code that uses $ */ })(jQuery)

There is a good description of closures and (function(){})() construct at http://ajaxian.com/archives/secrets-of-the-javascript-ninja-a-sneak-peak-for-ajaxians

$(document).ready()

To execute and modify DOM tree JavaScript function should usually wait until a page fully loads. With jQuery it looks like:

$(document).ready(function_name); 

In non-conflicting mode, code that executed in Trac on page startup is enveloped in closure and looks like:

jQuery(document).ready(function($) { ... }); 

Upgrade

Minified versions of a given release x.y.z of jQuery can be found in URLs with the following pattern:

http://code.jquery.com/jquery-x.y.z.min.js

Don't forget to update the default value for the jquery_location setting. See for example r11576.

jQuery UI

Since Trac version 1.0, we also bundle jQuery UI, a set of standard UI elements.

Upgrade

A specific x.y.z version of the minified Javascript code can be downloaded from URLs using the following pattern:

http://code.jquery.com/ui/x.y.z/jquery-ui.min.js

This correspond to the minified version of the whole of jQuery UI i.e. we don't use a subset of what is currently used by Trac on purpose, so that plugins can assume they have access to the all the jQuery UI components.

We use a custom theme for the CSS, built using the jQuery UI Theme Roller. The jquery-ui.css file contains a link to the theme roller with preselected values (link at the time of this writing, for Trac 1.0.0).

jQuery UI Timepicker Addon

We use the Timepicker extension for the standard jQuery UI datepicker.

We get the releases from the following URLs:

https://github.com/trentrichardson/jQuery-Timepicker-Addon/tree/v1.1.1

Get the release matching the jQuery UI version we use.

The jquery-ui-timepicker-addon.js file is usually compressed using the Google Closure Compiler, which gives good results. The minified file is saved in trac/htdocs/js/jquery-ui-addons.js.

Finally, the jquery-ui-timepicker-addon.css file is merged with the trac/htdocs/css/jquery-ui-addons.css file.

TracIni settings

After an upgrade, don't forget to update the default values for the jquery_ui_location and jquery_ui_theme_location settings. See for example r11576.

Last modified 15 months ago Last modified on Jan 27, 2013 3:07:07 PM