/library/javascripts/jquery/ReadMe.html

JQUERY HAS BEEN APPROVED FOR USE AT THE SBA.

jQuery Versions

In general, jquery.js and jquery.latest.js will be identical. However, there's a situation in which they will probably be different. When a new version of jQuery comes out, it will first be loaded to jquery.latest.js for testing. If it doesn't present any problems, it will be copied to jquery.js.

Therefore, you should use jquery.js for your applications (if you need to use it). That way, you won't be messed up by new version testing.

In a page that calls <cf_sbalookandfeel>, jquery.js is already loaded

The SBA Look-and-Feel menu ("SlafMenu") is the DHTML menu in the upper-left corner of the screen, under the question-mark icon. One of the problems with the SlafMenu is that it sometimes left the menu open, even after the user mouses out of it. This was a deficiency with using onmouseover and onmouseout. They don't track the mouse well enough. The jQuery "$(xxx).hover()" function does a much better job.

Therefore, one of the initial uses of jQuery at SBA was to fix the SlafMenu. Therefore, it's automatically loaded by the page with the <cf_sbalookandfeel> tag. Therefore, it's already available, without your having to load it, at least the official jquery.js file anyway.

In a frame of <cf_sbalookandfeel>, you have to load it yourself

You cannot use it as top.$(xxx) or even top.$(xxx, document). If you do that, it will continue to find elements only in top.document. It just doesn't work.

As you might guess, opener.$ also finds elements only in opener.document, no matter how hard you try to force it to use your pop-up window's document.

So, in general, if your jQuery call resides in a document that does not itself call <cf_sbalookandfeel>, you have to explicitly include it with

        <script src="/library/javascripts/jquery/jquery.js">

That's actually a symbolic link to the most recent "minified" version, so it's equivalent to jquery.min.js. There's really no good reason to use the unminified version in web pages. If you want to read the text of jQuery to see what it does, you'll have to look at jquery-xxx.js, where xxx is the version.

MSIE often breaks the web's caching rules to give the appearance of being faster than it really is. If you want to force MSIE to get the current version of jQuery, you can do so by including #Request.SlafTopOfHeadjQuery#, just as <cf_sbalookandfeel> does:

        <cfif NOT IsDefined("Request.SlafTopOfHeadjQuery")>
            <cfinclude template="/library/cfincludes/get_sbalookandfeel_topofhead.cfm">
        </cfif>
        <cfoutput>#Request.SlafTopOfHeadjQuery#</cfoutput>

SBA Custom jQuery Functions

SBA custom jQuery functions will also reside in /library/javascripts/jquery. If you see a custom functions file, such as HiGrpUtils.js, it has to be included after jquery.js. The JSInline attribute puts custom scripts after the include of jquery.js, so that shouldn't be a problem. Mainly, it would be a problem in a frame. So, for example, in a frame, you would include jquery.js, then HiGrpUtils.js.

jQuery Plug-Ins

To avoid file naming conflicts between jQuery plug-ins, in general, they will be kept in a subdirectory. So, for example, the FCKEditor plug-in resides in /library/javascripts/jquery/jquery.FCKEditor/jquery.FCKEditor.SBA.js. (That SBA part indicates that it's been edited to reference the FCKEditor according to SBA directory locations.)

Yes, that makes for some long URLs, if you don't use configuration variables. But with configuration variables it's easy:

    In Application.cfm (once for your entire app):

        <cfset Variables.LibURL        = "/library">
        <cfset Variables.LibJsURL      = "#Variables.LibURL#/javascripts">
        <cfset Variables.LibJsJqURL    = "#Variables.LibJsURL#/jquery">
        <cfset Variables.LibJsJqFckURL = "#Variables.LibJsJqURL#/jquery.FCKEditor">

    In your pages that are in frames or pop-ups:

        <script src="#Variables.LibJsJqURL#/jquery.js"></script>
        <script src="#Variables.LibJsJqFckURL#/jquery.FCKEditor.SBA.js"></script>

Sizzle (sizzle.js)

Sizzle (file name sizzle.js) is the CSS selection engine part of jQuery (just that one part of it and no more). For this reason, we will always keep our symbolic links to Sizzle in the same directory as jQuery. If you don't need the full power of jQuery and want to speed up your page's JavaScript processing, you can include sizzle.js (with a lower case s) instead. But you still have to access the Sizzle object itself as Sizzle (with a capital S). That's just the way the Sizzle group did things. For example:

        <script src="#Variables.LibJsJqURL#/sizzle.js"></script>
        ...
        <script>
        function HighlightHotlinks (pColor)
            {
            var sHotlinks = Sizzle("a.highlightable");  // CSS selector for "hotlinks with the highlightable class". 
            for (var i = 0; i < sHotlinks.length; i++)
                sHotlinks[i].style.backgroundColor = pColor;
            }
        </script>

Library Maintenance Scripts ("productname.make_current_by_version_number.sh")

Both jQuery and Sizzle have "make_current_by_version_number" shell scripts (.sh) to update all of the symbolic links when a new version comes along. To run them, you have to have command-line access to the development server with proper group permissions. As their names suggest, both scripts take just the version number as their sole argument. For example, to set the current jQuery symbolic links to point to version 1.6.4:

        > cd /opt/iplanet/servers/docs/library/javascripts/jquery
        > jquery.make_current_by_version_number.sh 1.6.4