Javascript for themes

[isaacfreeman]

Designers building themes are used to adding links to jQuery and other JS libraries. A lot of the time they only need to add

<%= javascript_include_tag "breeze/breeze" %>

and they'll already have jQuery and jQUery UI.

We need some documentation explaining this, so designers don't load multiple copies of jQuery from different sources. Apart from extra load time, this can cause weird behaviour. For example, when they're using Breeze Commerce, two instances of jQuery means that every Add to Cart action occurs twice.

Designers need to know...

1. that they need to have breeze.js in their templates
2. that for simple projects they won't need anything more than breeze.js
3. the list of other JS files that breeze.js will load for them, including jQuery

[sam-law]

I would question why we build jquery into breeze, as opposed to including it from Google, where most users will already have a cached copy. https://developers.google.com/speed/libraries/

[isaacfreeman]

There are a few factors to balance (off the top of my head – let me know if I have any of this wrong):

1. We need to ensure jQuery is present for Breeze to work.
2. An unfinished or broken theme might not have a jQuery, making Breeze unusable on the front end.
3. We want to serve all Javascript through the Rails asset pipeline.
4. We want to use the standard jQuery CDN, as people probably already have this cached.
5. The asset pipeline doesn't (as far as I know) allow us to call from the CDN.
6. The overall performance boost from using the asset pipeline consistently, even if we include jQuery is much greater than the boost from using jQuery's CDN alone.

We've taken the approach of serving our own copy of jQuery through the pipeline. A couple of other approaches we could consider...

• Take jQuery out of the asset pipeline and require theme developers to include it for the front end, using the CDN if they choose.
• Inject jQuery into the page automatically. This would ensure it's present, but makes it more confusing for people trying to work out why their page is loading Javascript they didn't ask for.

[sam-law]

It's just I notice the jquery website itself uses the Google api

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

I guess from the Google site there's 1 year of caching, whereas the asset pipeline is going to change it every time we change any of the on-site javascript, though presumably that's almost never, and as you say the benefit from an external source is probably negated by the asset pipeline.

Just bringing it up as a question, since we're going to modify it. :)

I've seen people use the google api callback code to ensure specific stuff only loads once jquery has loaded, but I assume it's far too complicated for our uses.

<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("jquery", "1.8.3", {"callback" : jqueryLoaded});
  google.load("jqueryui", "1.9.2" {"callback" : jqueryuiLoaded});
</script>

So you can hook stuff up to the callbacks

function jqueryLoaded() {
  //stuff that should be run now that jquery is loaded
}

The benefit being you can load the page without scripts, and have them load in afterwards. But this obviously doesn't work in the breeze backend. https://developers.google.com/loader/

[isaacfreeman]

Closing this one. Instead of documentation, we've gone with a default theme template which people can install at the beginning of a project. This includes the javascript tag for breeze/breeze.

Whether this is the best way to include jQuery is something we could test separately.