Bootstrapping your way to victory.
Important! Steps 1 to 3 are required for all developers that will be modifying styles. If a project is already bootstrapped, then steps 4 to 6 can be ignored.
Ruby is required to download the bootstrapper as well as to build the compass styles. You can either download it from the official Ruby website or get the Windows installer from RubyInstaller.org.
Bootstrapper styles are packaged into a Ruby gem for easy distribution and installation. To install bootstrapper on your machine, just run the following commands:
gem sources -a http://iq-vcmacsrvr001:9292/ gem install iQ.Bootstrap
Bootstrapper updates need to be checked manually (for now). This can be done by using the following command:
iqbootstrap update
It is important to stay on the latest version of the Bootstrapper. If you're not, then styles could conflict when compiling the styles.
To bootstrap your project, run the following commands:
cd ./to/your/project/root iqbootstrap install
The iqbootstrap install command has a few options you can set:
Usage:
iqbootstrap install
Options:
-s, [--sass=SASS] # sass directory
# Default: sass
-c, [--css=CSS] # css directory
# Default: css
-j, [--js=JS] # javascript directory
# Default: js
-i, [--img=IMG] # image directory
# Default: img
After installing the bootstrapper, the following files will get added to your project:
./<sass_dir>/_iq.bootstrap.scss #Required imports ./config.rb #Config file specifying folder structure ./PIE.htc #.htc file for CSS3 styles in IE < 9 ./shim.htc #.htc file to enable HTML5 elements in IE < 9
.htc files can not be loaded from other domains, so this must be hosted in your project root directory.
Create a .scss file in your sass folder which will set up the base colors, fonts, etc. This file is where you will override the default variables for your project. At the end of your file, you must add @import 'iq.bootstrap'; to include the bootstrapper styles.
Heads Up! The variables must be set before importing the iq.bootstrap file.
//Example styles.scss file $navbarBackground: #07A; $navbarBackgroundHighlight: #06A; $navbarLinkColor: #0BE; $headingsColor: #048; @import "iq.bootstrap";
The last thing you need to do is to compile your .scss files, and include the compiled .css files in your project. When referencing the styles in your HTML, reference the compiled .css file. Also make sure that the style compiled from the .scss file in step 6 is the first style in your <head> tag.
To compile your sass, you can do one of the following:
This will only compile the styles once, and needs to be run every time a change is made to a .scss file.
compass compile
Compass watch will automatically compile the .scss files every time a .scss file is saved. The process will run in the background.
compass watch
Use the iQ.Bootstrapper javascript plugin to load the plugins that you need for your web project. Load iq.bootstrapper.min.js from CDN in the <head> section of your HTML, and use Bootstrap.load() to load your plugins.
Important! iq.bootstrapper.min.js needs to be the first script that's loaded in the <head> section!
<script type="text/javascript" src="//commonstaging.iqmetrix.net/js/iq.bootstrap.min.js"></script>
<script type="text/javascript">
Bootstrap.load("jquery");
</script>
Loads a single or list of plugins, and runs the callback function when all plugins are loaded. Plugins can be one of the following:
A plugin object looks like the following:
{
name: "backbone", //Name of plugin on the iQmetrix CDN
url: "./path/to/script", //Path to external js file for scripts not hosted on iQmetrix CDN
dependencies: ["underscore"], //An array of dependencies. Only applicable to external scripts
version: "1.2.3", //Version for the script. Only applicable to CDN scripts
debug: true //Loads debug (non-minified) script if true. default: false
}
Heads up! The name or url must be specified to be a valid plugin object. The other values are optional.
Pro Tip! A short-hand way to specify an external plugin is to add @ in front of the url, instead of specifying an object. If you load an external script this way, however, you cannot specify dependencies, version, or debug mode. See example #6 below.
Here are some examples of different ways to use the plugins parameter:
Bootstrap.load("jquery");
Bootstrap.load([ "jquery", "backbone" ]);
Bootstrap.load(
{ name: "jquery", version: "1.7.2", debug: true },
{ url: "/path/to/script" }
);
Bootstrap.load([
"jquery",
{ name: "backbone", version: "0.9.2" },
"datejs"
]);
Bootstrap.load([
{ url: "/js/utils.js", dependencies: ["jquery"] },
{ url: "/some/script.js" }
]);
//These two loads are exactly the same:
Bootstrap.load(
{ url: "/path/to/external.js" }
);
//This is a shorthand version of the above call.
Bootstrap.load(
"@/path/to/external.js"
);
This method is similar to the callback parameter in Bootstrap.load(plugins, callback). However, there is a difference.
The callback in Bootstrap.load() will trigger when all of the plugins in that load call are loaded.
The callback in Bootstrap.wait() will trigger when all plugins are loaded, from all load calls.
In this example, when script1, script2, and script3 are done loading, a will get printed. When script4 is done loading, b will get printed. When all four scripts are done loading, c will get printed. However, because the two load calls are asynchronous, it's possible that b will print before a, but in both cases, c will get printed last. This will work regardless of if you chain the calls or not.
Pro Tip: Best practice is to Bootstrap.load() all your global plugins (plugins required on every page in the project) in the template, and only load scripts needed per page in that page's javascript file.
Bootstrap
.load(
["script1","script2","script3"],
function() {
console.log("a");
})
.load(
"script4",
function() {
console.log("b");
})
.wait(function() {
console.log("c");
});
You can view an example of a project that has been bootstrapped here. Take note of the strapon.js file which sets up the namespacing for the project and loads global plugins, and the individual /js/index#.js files which load only required plugins for that page.