[[PageOutline(2-5,Contents,pullout)]]

= !JavaScript for Trac and plugin development

!JavaScript is used in Trac to add dynamics to web interface elements on the browser side:
 * expanding/folding in the TracBrowser
 * providing [TracAccessibility keyboard shortcuts]
 * and many other features

This page lists some of the uses of this language in Trac.

{{{
#!comment
list other uses of JS in Trac
}}}

We also adhere to a [TracDev/CodingStyle#JavaScript JavaScript coding style].

== Third party libraries

=== jQuery

Trac makes heavy use of [wikipedia:JQuery jQuery] library. Access to this library contents is provided through the main function named `$`, which is just a shortcut for the ''jQuery'' namespace and it is possible to use the full name instead. However, other libraries may use `$` too, which may cause conflicts. To avoid these conflicts, switch jQuery into non-conflict mode with ''jQuery.noConflict()'' call. This is well explained in http://docs.jquery.com/Using_jQuery_with_Other_Libraries.

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 the DOM tree the JavaScript function should 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 [changeset:16094/trunk/trac/web/chrome.py r16094].

=== jQuery UI

Since Trac version 1.0, we also bundle [http://jqueryui.com jQuery UI], a set of standard user interface elements (UI).

==== 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, ie we don't use a subset of what is currently used by Trac on purpose, so that plugins can assume they have access to all jQuery UI components.

We use a custom theme for the CSS, built using the jQuery UI Theme Roller.
The [source:trunk/trac/htdocs/css/jquery-ui/jquery-ui.css@11493:50#40 jquery-ui.css] file contains a link to the theme roller with preselected values. [http://jqueryui.com/themeroller/?ctl=themeroller&ffDefault=Verdana,Arial,'Bitstream%20Vera%20Sans',Helvetica,sans-serif&fwDefault=normal&fsDefault=13px&cornerRadius=.3em&bgColorHeader=ffffdd&bgTextureHeader=03_highlight_soft.png&bgImgOpacityHeader=80&borderColorHeader=bbbbbb&fcHeader=000000&iconColorHeader=707070&bgColorContent=ffffff&bgTextureContent=01_flat.png&bgImgOpacityContent=00&borderColorContent=bbbbbb&fcContent=000000&iconColorContent=222222&bgColorDefault=ffffff&bgTextureDefault=01_flat.png&bgImgOpacityDefault=0&borderColorDefault=bbbbbb&fcDefault=b00000&iconColorDefault=b00000&bgColorHover=ffffdd&bgTextureHover=01_flat.png&bgImgOpacityHover=0&borderColorHover=505050&fcHover=505050&iconColorHover=505050&bgColorActive=303030&bgTextureActive=03_highlight_soft.png&bgImgOpacityActive=30&borderColorActive=bbbbbb&fcActive=eeeeee&iconColorActive=d7d7d7&bgColorHighlight=c0f0c0&bgTextureHighlight=03_highlight_soft.png&bgImgOpacityHighlight=75&borderColorHighlight=c0f0c0&fcHighlight=363636&iconColorHighlight=4b954f&bgColorError=ffddcc&bgTextureError=08_diagonals_thick.png&bgImgOpacityError=18&borderColorError=9b081d&fcError=500000&iconColorError=9b081d&bgColorOverlay=666666&bgTextureOverlay=08_diagonals_thick.png&bgImgOpacityOverlay=20&opacityOverlay=50&bgColorShadow=000000&bgTextureShadow=01_flat.png&bgImgOpacityShadow=10&opacityShadow=20&thicknessShadow=5px&offsetTopShadow=-5px&offsetLeftShadow=-5px&cornerRadiusShadow=5px Themeroller link] for Trac 1.0.0.

==== jQuery UI Timepicker Addon #Timepicker

We use the [http://trentrichardson.com/examples/timepicker/ Timepicker extension] for the standard jQuery UI datepicker.

Get the release that matches the jQuery UI version:
  `https://github.com/trentrichardson/jQuery-Timepicker-Addon/tree/v1.1.1`

The `jquery-ui-timepicker-addon.js` file is usually compressed using the [https://developers.google.com/closure/compiler/ Google Closure Compiler], which gives good results. The minified file is saved in [source:trunk/trac/htdocs/js/jquery-ui-addons.js trac/htdocs/js/jquery-ui-addons.js].

Finally, the `jquery-ui-timepicker-addon.css` file is merged with the [source:trunk/trac/htdocs/css/jquery-ui-addons.css 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 [changeset:16094/trunk/trac/web/chrome.py r16094].