#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 functiongetRootCssVariable
- A function for returning a given CSS Variable from the document rootjsLibs
- A getter function which returns an array of strings defined on thebody
tag underdata-js-libs
jsLibIsActive
- A function that returns a boolean saying whether a particular string is defined indata-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.#Turbolinks
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
.