KISO Docs
KISO Docs

Javascript

#The Rapid Rails Themes Kernel

Rapid Rails Themes ships with a super small internal API that you can also use. It's available globally on the window object as RRT. For example:
  RRT.jsLibs('gmaps');
It provides some simple, but handy functions:
  • hookOnPageLoad - A wrapper hook that will correctly initialize JS functions, automatically detecting whether you are using Turbolinks or standard jQuery.
  • debounce - A debounce function
  • getRootCssVariable - A function for returning a given CSS Variable from the document root
  • jsLibs - A getter function which returns an array of strings defined on the body tag under data-js-libs
  • jsLibIsActive - A function that returns a boolean saying whether a particular string is defined in data-js-libs
#How the Kernel is used to enable JS plugins.
All external JS plugins shipped with Rapid Rails Themes are wrapped in a loader function:
//= require vendor/jasny/jasny_bootstrap

(function() {

  function initJasny() {
  }

  RRT.hookOnPageLoad( function() {
    RRT.jsLibIsActive('jasny') && initJasny.call(this)
  })

})()
This allows for any particular JS plugin to be turned on or off on a given page simply by putting the string on the body tag's data-js-libs attribute.
Hoo boy. Turbolinks is great and all, but you really have to read their documentation and know what you're doing. You can very easily run into situations when using jQuery plugins where things start breaking or acting weirdly.
Rapid Rails Themes is designed to work with Turbolinks out of the box, so you shouldn't run into any problems out of the gate.

#Plugins shipped with Rapid Rails Themes

!info I need something not listed! If there's a plugin you'd like to see bundled - let me know! Email john@rapidrailsthemes.com.
Here's the current list of JS plugins shipped with Rapid Rails Themes:
  • Bootstrap Switch
  • ChartJS
  • Clipboard.js
  • Countdown.js
  • countTo.js
  • Easy Pie Chart
  • Fastclick
  • FitIE
  • Flot
  • Jasny Bootstrap
  • jqVectorMaps
  • Metis Menu
  • Parallax.js
  • Popper.js
  • Prettify
  • Prism.js
  • Slimscroll
  • Sparklines.js

#Customizing the included Javascript libraries

First, you will need to run the customization generator rrt:customize. This will generate an rrt.js file, which contains the imports for all external libraries. You can now edit that file to remove anything you don't need, but be sure to not remove Bootstrap itself - unless you really mean to.
Next, take a look at the view partial in views/layouts/_external_js_libs.html.erb. This contains code which handles the loading of particularly heavy JS libraries:
  • Modernizr
  • GMaps
  • Flot
  • ChartJS
You can remove whichever libraries you don't intend to use.
Finally, in the views/layouts/_base layout there are special tags on the body element under the data-js-libs data attribute. Remove any of the default libraries from this attribute that you don't need. Search your project for the string content_for :js_libs and review any additional JS libs that are loaded on a per-view basis that you might not want (dashboard demo libraries for example).

#Ordering of Javascript external libraries in _base layout

There is a specific order possible to how Javascript libraries are rendered to the page. In order:
  • :external_js_libs
  • Your application.js
  • :javascript
This allows you to specify exactly those libraries which should be rendered out before everything else, or are otherwise not part of your asset pipeline manifest in application.js.

#Activating libraries in external_js_libs for inclusion in the rendered output

Let's say you have a specific page that you want to load Google Maps on, and only that page. To have the appropriate external JS libs be rendered to the output, you'd need to include the following on that specific page:
<% content_for :js_libs, "gmaps" %>
This will cause the Google Maps include tag to be rendered in _external_js_libs.html.erb.

#Adding additional libraries to _external_js_libs.html.erb

All you have to do is place the javascript_include_tag in a wrapper clause that checks the @js_libs instance variable for inclusion of a library name you specified in your content_for :js_libs tag:
<% if @js_libs.include? 'chartjs' %>
  <% content_for :javascript do %>
    <%= javascript_include_tag "vendor/chartjs/Chart.bundle.min" %>
    <%= javascript_include_tag "vendor/chartjs/Chart.min" %>
  <% end %>
<% end %>
That block of code would be rendered when a content_for :js_libs, 'chartjs' tag is encountered on a page.
In this case I've also chosen to have the include tags rendered into the :javascript content placeholder in the _base layout - this means it will be rendered after the main application javascripts, and after the :external_js_libs content placeholder.

#Removing the Demo JS code

Once you run the customization generator as above, you can simply remove all require statements that reference rrt/demo.
Contents