Using jQuery with Sitemagic CMS

Sitemagic CMS features nothing less than the best jQuery implementation on the planet. Our framework is the only of its kind that lets you load multiple versions of jQuery, completely isolated from one another. You target the version of jQuery you like, and your code will keep using that version of jQuery, no matter what other extension may load, and even when new versions of Sitemagic CMS and jQuery is released.
Key advantages of using jQuery with Sitemagic CMS:
  • Load multiple versions of jQuery
  • All jQuery instances run isolated from one another
     - Various extensions won't break each other
  • jQuery loads completely non-blocking - website loads faster
  • Loads from Google CDN or alternative source
  • Outstanding performance and caching when loading from CDN
  • New releases are immediately available on CDN
    - no need to wait for a new version of Sitemagic CMS
  • Your jQuery code never breaks - it will keep running on the
    version of jQuery it was designed for.
Some drawbacks:
  • May not work with poorly designed jQuery plugins that rely
    on the existence of a globally accessible jQuery instance.
    See notes regarding this problem at the end of the document.
  • Using jQuery UI requires you to build you own theme
    with a unique CSS Scope (which can be set when downloading
    the theme). Fortunately this is very easy.
For standard jQuery operations (using just the $ variable), there is really not much to consider. Here is an example of how easy it is:
SMResourceManager.Jquery.Run("1.10.2", function($)
{
    alert("jQuery version " + $.fn.jquery + " loaded!");
});
The example above dynamically loads jQuery version 1.10.2. When jQuery is loaded, the callback function is invoked, passing the jQuery instance as an argument. In this case the jQuery instance is simply used to alert the jQuery version number.
For more advanced options, use the Load function instead. The example below demonstrates how it is possible to load jQuery, jQuery UI + a custom UI theme, and a custom plugin, in just one single operation. Various callbacks allows us to interact when certain resources have finished loading.
SMResourceManager.Jquery.Load(
{
     version: "1.10.2",
     uiversion: "1.10.3",
     loaded: function($, cfg)
     {
         alert("jQuery version " + $.fn.jquery + " loaded!");
     },
     styles:
     [
         {
             source: "extensions/test/ui/jquery-ui-1.10.3.custom.css",
             loaded: function($, style)
             {
                 alert("CSS file " + style.source + " loaded!");
             }
         }
     ],
     plugins:
     [
         {
             source: "extensions/test/tabs.jquery.js",
             loaded: function($, plugin)
             {
                 alert("Plugin " + plugin.source + " loaded!");
             }
         }
     ],
     complete: function($, cfg)
     {
         alert("All resources have been loaded");
     }
});
Let's examine the configuration object passed to the Load function.
version : This property is used to specify the desired version of jQuery. List of available versions.
uiversion : This property is used to specify the desired version of jQuery UI. List of available versions. jQuery UI can also be loaded like any other plugin using the plugins array, which allows us to attach a loaded callback.
styles : Array of configuration objects defining a source property (path) to a stylesheet. A loaded property is used to define a callback which is invoked when the stylesheet has been loaded.
plugins : Array of configuration objects defining a source property (path) to a jQuery plugin. A loaded property is used to define a callback which is invoked when the plugin has been loaded. Notice that plugins are chain loaded in the order specified, to make sure dependencies are loaded first.
complete : Used to specify a callback which is invoked when all resources have finished loading.
Loading jQuery from an alternative source - e.g. a locale copy or from an alternative CDN - is also possible. Simply replace the version property with a source property as shown below:
SMResourceManager.Jquery.Load(
{
     source: "extensions/test/jquery-1.10.2.min.js",
     styles:
     [
         {
             source: "extensions/test/ui/jquery-ui-1.10.3.custom.css",
         }
     ],
     plugins:
     [
         {
             source: "extensions/test/ui/jquery-ui-1.10.3.min.js",
         }
     ],
     complete: function($, cfg)
     {
         alert("jQuery and jQuery UI has been loaded");
     }
});
In the example above we load a locale copy of both jQuery and jQuery UI.
If a jQuery plugin is not working

If you find that a jQuery plugin does not work when loaded using SMResourceManager.Jquery.Load, it's most likely because the plugin is poorly written. In most cases a plugin breaks because it refers to window.jQuery or window.$ rather than the instance passed to the anonymous plugin function. Example of simple jQuery plugin wrapper:
(function($)
{
     // All of these lines are wrong and not uncommon mistakes:
     console.log("jQuery version " + window.jQuery.fn.jquery + " loaded");
     console.log("jQuery version " + window.$.fn.jquery + " loaded");
     console.log("jQuery version " + jQuery.fn.jquery + " loaded");
})(jQuery);
Solution: In most cases you can simply search and replace the references to window.jQuery, jQuery, and window.$ with $. Example above after fixing it:
(function($)
{
     console.log("jQuery version " + $.fn.jquery + " loaded");
     console.log("jQuery version " + $.fn.jquery + " loaded");
     console.log("jQuery version " + $.fn.jquery + " loaded");
})(jQuery); // This is the only place where jQuery can be referenced