Ci logo

Technology

StyleBitz & JavaScript

This page will outline lower level details of any UI component that uses JavaScript. It is also the place to learn about the Rails integration with our JavaScript assets. Our JavaScript is broken down into logical layers that allow you full control over what is used. If you are using StyleBitz with Rails, most of this is done for you automatically. Here is an overview below. Remember, a "manifest" is automatically pre-compiled for you as part of the Rails engine integration.

  1. Manifest: style_bitz.js - The job of this top level asset is to (a) require external dependencies and (b) require StyleBitz core. Some dependencies are your responsibility to satisfy, others are vendored within StyleBitz.
  2. Asset: style_bitz/core.js - Is required from the manifest above. The JavaScript in this file and those required below it encapsulate all progressive enhancements to our base elements as well as corresponding UI component behavior.
  3. Manifest style_bitz/metrics.js - A bundled of the following three manifests. Please see the Metrics Helper documentation for full details.
    • Manifest/Asset: style_bitz/metrics/interactions.js - Allows us to use StyleBitz.interactions.pageTest(...) tests.

Metrics

We have backported Interaction JavaScript from our old style guide. Please use these before and after examples when switcing a page to StyleBitz vs our old StyleGuide and INK.js. Any other INK.js helpers can now be written in pure ES5 JavaScript too since we target IE11 and up.

// Before/After/After
INK.interactions.pageTest("acq.groups");
StyleBitz.interactions.pageTest("acq.groups");
CustomInk.Metrics.pageTest("acq.groups");

Events

Walk this walk!

StyleBitz provides custom events for most UI component actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. show) is triggered at the start of an event, and its past participle form (ex. shown) is triggered on the completion of an action.

All events are namespaced and infinitive events provide preventDefault functionality. This provides the ability to stop the execution of an action before it starts. TODO/LEARN:

JavaScript Assets

The StyleBitz gem exposes a main JavaScript style_bitz.js Sprockets asset. This file assumes you have met the following dependencies somehow via your Sprockets load path.

//= require jquery_ujs

These requirements will be met by the jquery-rails gem which is included by default in new Rails projects.

gem 'jquery-rails'

But remember, the jquery-rails gem will put jQuery in your asset path, but it is less about jQuery and more about UJS behavior. Hence the versions of these gems are always likely behind. For this reason we have set jQuery to be its own <script> tag via jQuery's MaxCDN usage. By default this is set to v1.12.4 and can be configured to a different version.

<% sb_jquery_version_set '3.2.1' %>

Vendored Assets

Our main JavaScript asset also requires the following assets. These assets are vendored within the StyleBitz gem and need not be packaged locally. Note, that it is possible that each vendored asset adds to properties to the top level window object too. It is not our concern now to champion a module system since we are primary being used within Rails applications. Feedback welcome.

Each of these assets is vendored in a style_bitz subdirectory. This means that our JS manifest uses a namespaced require, for example, style_bitz/enquire vs just enquire. Doing so means:

/vendor/assets/javascript/style_bitz/jquery.cookie

Our Namespace

The StyleBitz gem creates a top level window.StyleBitz namespace. This is the only leaked property/variable to your document. Here is an overview of the top level properties withing this namespace.

StyleBitz.Breakpoints & .Layouts

We recommend using enquire.js when needing to solve appropriate problems that require JavaScript be breakpoint aware. A great example of one need is written on the walkthrough section of the enquire website. Other smaller examples could be that you want your elements to use different SUIT modifier classes at breakpoints that make sense for you. The namespaced JavaScript gives you the following media query handles. These can enable to work with any StyleBitz layout as if you were using sb-breakpoint and sb-respond-to.

> StyleBitz.Breakpoints
< Object
  lg: "(min-width: 64em)"
  md: "(min-width: 43.75em)"
  xl: "(min-width: 81.25em)"
> StyleBitz.Layouts
< Object
  lg: "(min-width: 64em) and (max-width: 81.1875em)"
  md: "(min-width: 43.75em) and (max-width: 63.9375em)"
  sm: "(max-width: 43.6875em)"
  xl: "(min-width: 81.25em)"

Armed with these properties, you could easily be notified of loaded or entered layouts. For example, the following CoffeeScript would log layout names to the console on page load and scren resize using enquire.js.

enquire.register StyleBitz.Layouts.sm, -> console.log 'sm'
enquire.register StyleBitz.Layouts.md, -> console.log 'md'
enquire.register StyleBitz.Layouts.lg, -> console.log 'lg'
enquire.register StyleBitz.Layouts.xl, -> console.log 'xl'

StyleBitz.Forms

As of now, many of the JavaScript objects augment simple form behavior. We will document more as we build jQuery interfaces and events as needed.

Document StyleBitz.Forms.Indicator.
Document StyleBitz.Forms.Label.
Document StyleBitz.Forms.Stepper.

Alerts & Dialogs

This helper allows you to work with alert and dialog components. There are two classes for wrapping an individual alert or dialog and their respective names are StyleBitz.AlertClass and StyleBitz.DialogClass. However, the JavsScript will attempt to create a singleton instance for the first alert or dialog found on the page during the DOM loaded event. These are assigned to StyleBitz.Alert and/or StyleBitz.Dialog and are the preferred way of working with these two components unless you need to build your own instances.

Assuming you have the singleton or any self instantiated instance, here are the interfaces. Also, reading the source of the class(es) is always a good option too for the advanced user.

StyleBitz.Alert

Success

  • Run - @alert.success "<p>Success</p>"
  • Run - @alert.info "<p>Info</p>"
  • Run - @alert.warrning "<h3>Warning</h3><p>Be advised!</p>"
  • Run - @alert.error "<h3>Error</h3><p>Please fix!</p>"

StyleBitz.Dialog

Account preferences updated.

  • Run - @dialog.success "<h3>Account preferences updated.</h3>"
  • Run - @dialog.info "<h3>Thanks for subscribing.</h3>"
  • Run - @dialog.warning "<h3>Credit card is about to expire.</h3>"
  • Run - @dialog.error "<h3>Whoops! Missing information.</h3>"

StyleBitz.Utils

Misc utility functions.