Ci logo

Technology

StyleBitz ❤️ Rails.

On top of all the goodness of our own Sass framework using the StyleBitz gem with Rails will give you access to mobile first responsive views and pre-defined layouts that automatically render common CustomInk components like our header and footer. StyleBitz allows you to take as much or as little as you want. You are in full control.

Usage

To use StyleBitz with Rails, just add it to your Gemfile. If needed, you can use a semantic version tag. See our Change Log for details.

gem 'style_bitz', github: 'customink/style_bitz'

Layouts & Views

Since StyleBitz is all about mobile first responsive design, it has only a single Rails layout. We call this the core layout. The core layout's responsibility is very small. It's job is to include other core partials to assemble a working page.

class ProductsController < ApplicationController
  layout 'style_bitz/layouts/core'
end

Advanced Layouts

The core layout supports a Rails nested layout strategy. For example, you can create your own custom layout and yield content to :sb_main. In this way, you can abstract all customizations to the core layout in one place. Read more in the helpers section for core too.

<%= content_for(:sb_main) { yield } %>
<%= render template: 'style_bitz/layouts/core' %>

Another way of leveraging the StyleBitz layout from a view-first perspective is to use the sb_layout method. Call this method at the end of your view to force the style_bitz/layouts/core layout. Great for the SiteContent team/app. For example:

<h1>My Content Page</h1>
<% sb_layout %>

Partial: style_bitz/core/page_toolbar

The page toolbar partial is shown by default and is hidden when the header is condensed. See below for condensed header options. Content within the tool bar is a simple message (left) and links (right) which default to user account links. The partial exposes the following interfaces:

Please see the core helpers for additional details to configure the page toolbar.

Partial: style_bitz/core/head

This partial puts all of our common head elements that you would expect – title, mobile compatible hints, etc. It also has a stylesheet link tag for the style_bitz/style_bitz manifest. This is the fully rendered core CSS as explained in our Sass framework section and it is automatically added to your applications precompile list. StyleBitz does this so it can be cached between requests. It also exposes the following interfaces:

  1. A content for yield to :sb_head_pre at the very top. Use this for custom tags like title or meta content.
  2. A content for yield to :sb_head at the very end to add CSS or JavaScript after core.
  3. A content for :sb_page_title to customize the title tag. Alternatively, you can use the sb_set_page_title('New Title') helper method.

If no :sb_head_pre content block is given, we will render out a default title, and description meta tags. When using a custom content_for block we will scan your HTML and make sure to not include any default that could conflict with yours.

This partial also inserts the Rails csrf_meta_tags to help protect from forgery protection. Please read the JavaScript Assets section for more info on Rails JavaScript deps to leverage this meta tag.

There are 14 icon meta tags to fill in. Get some from SG mobile_phone.html.erb assets.

Partial: style_bitz/core/header

This partial renders our responsive header and mobile/desktop menus. In various places, it includes a customizeable TTARP number that is also hooked into our standard TTARP cookie override system. Meaning, TTARP number cookies set in older pages will still render in StyleBitz. Please see the TTARP Helper section for more details.

To set a menu item as selected, use the <% sb_menu_select :products %> helper. This takes a symbol that matches any one of the following:

For a condensed header. Please use thew <% sb_header_condensed! %> in your views. This will render the page with no menus at all. Great for pages that focus on a distinct task.

Partial: style_bitz/core/header/tapas

The header contains the primary menu. For a smaler secondary menu, you need Tapas. Rendering this menu is as simple as yielding some content for it. For example:

<% content_for(:sb_tapas) do %>
  <div class="sb-Wrapper">
    <ul class="sb-Tapas-nav">
      <li class="sb-Tapas-nav-item is-Selected">One</li>
      <li class="sb-Tapas-nav-item">Two</li>
    </ul>
  </div>
<% end %>

The tapas menu is sticky (with CSS) just like the primary menu, becuase it resides within the sticker header. This is by design. Content in this menu can be anything and sub component styleing is lean and only incudes simple lists as shown above.

Taps Menu Demo

This partial is our fully responsive footer. It loads the StyleBitz JavaScript manifest, please see the JavaScript section to learn more about what assets are loaded and how to use custom JavaScript for your pages. The footer exposes the following programtic interfaces.

  1. A content for yield to :sb_footer at the very end to add other content and/or JavaScript.

For a condensed footer. Please use thew <% sb_footer_condensed! %> in your views. This will render the footer with very little content. Great for pages that focus on a distinct task.

Location Services

StyleBitz makes it easy to leverage basic information about a users IP address. We do this with the help of our Sonar gem that wraps our MaxMind DB subscription to decode IP address to city information.

Exposed interfaces focus on using JavaScript via the client to enhance the customers' experience. Do this using the StyleBitz.Location object. It has two methods, one for info, another for promos. Both leverage a jQuery deferred object as the return value since both make XHR requests for data. Use that returned deferred object or pass a function to the method which will be passed as .done to that same deferred for you. For example:

 StyleBitz.Location.info((info)=>{ console.log(info); })
 Object
    city: "Richmond"
    coordinates: [37.6273, -77.5437]
    country: {short: "US", long: "United States"}
    postal_code: "23228"
    subdivision: {short: "VA", long: "Virginia"}
    time_zone: "America/New_York"

The postal_code value will likely be the most useful and we can always add more as needed. The data sources for this rely on one frontend application mounting the required paths as follows. As of this writing, that application will be SiteContent.

get '/ink/sb-localinfo' => 'style_bitz/location#info', format: :json
get '/ink/sb-localpromos' => 'style_bitz/location#promos', format: :json

Error Pages

404 Not Found page screenshot StyleBitz provides a standard, responsive error page for the following HTTP error codes:

There are two basic ways to allow your host application to serve these pages:

  1. Let StyleBitz::ErrorPagesController render and serve pages (typical)
  2. Use StyleBitz::ErrorPagesRendering to simply render pages, allowing your host application to trigger rendering manually

Using StyleBitz::ErrorPagesController

Simply add the following at the end of the config block in config/application.rb:

config.exceptions_app = self.routes

This ensures that Rails defers to config/routes.rb file to find error pages. Then in config/routes.rb add the following routes to point each path at StyleBitz:

match '/404' => StyleBitz::ErrorPagesController.action(:not_found), via: :all
match '/422' => StyleBitz::ErrorPagesController.action(:unprocessable_entity), via: :all
match '/500' => StyleBitz::ErrorPagesController.action(:internal_server_error), via: :all

StyleBitz drops static 404.html, 422.html, and 500.html files in the public directory of the host application. This allows upstream servers to provide fallback error pages in the event the Rails application cannot respond. Since these files are only written to disk when they do not already exist, make sure the following files are removed (and preferably .gitignored) prior to running your app with StyleBitz serving error pages:

There is a timestamp rendered into an HTML comment at the bottom of each rendered error page.

If you have any catch-all routes at the end of your routes file, you may need to place these routes before them.

Note that in order to view these pages in the development environment, you must change this line in config/environments/development.rb from true to false:

config.consider_all_requests_local = true

Using StyleBitz::ErrorPagesRendering

You may need more control over when or how an error page is rendered. Include the StyleBitz::ErrorPagesRendering concern in any controllers you want to empower to serve error pages. Then you can use the #sb_error_page_for method to trigger the same behavior in a controller action. Example:

def not_found
  error_page_for "404"
end

Feel free to use one or both approaches!

Form Helpers

Building our forms is complicated work. StyleBitz solves a lot of this complicated work by not requiring you to add extraneous class names to a form's sub elements. Our Rails engine provides a few simple helpers to make building forms a bit easier.

Our Form Builder

The sb_form_for helper is built on top of Rails form_for. It does all the work of setting up the sb-Form class to your form.

<%= sb_form_for user, url: '#', html: {...} do |u| %>
  ...
<% end %>

Using our form helper also helps ensure that Rails field with errors automatically works too! If you find your self manually coding up is-fieldWithErrors classes, please use our helper instead. For an example, see our demo form error page.

Other Helpers

If you add a new helper module to StyleBitz, please follow these guidelines:

  1. Avoid name conflicts and prefix all method names with sb_.
  2. Include the new helper in the StyleBitz::ApplicationHelper module.

There is no need to include helpers in your host application. StyleBitz will prepare your application by including our root application helper for you.

Core Helper

A few advanced features of the core helper.

Since most of these helpers set up instance variables that communicate to the rendered layout, StyleBitz has made it easy to call these helpers in a declarative fashion from the controller context. For example this controller setup would keep each of your views from doing the same work over and over again if you were not using advanced layout techniques described above.

layout 'style_bitz/layouts/core'
before_filter :sb_layout_condensed!,
              :sb_main_wrapped!,
              :sb_main_content!
<%sb_header_cta_custom! %>
<% content_for :sb_header_cta_custom do %>
  <%= sb_render_ttarp_header %>
<% end %>

TTARP Helper

Divergent from our legacy StyleGuide, the StyleBitz gem does not champion named TTARP numbers like :sales. We felt this feature is out of Scope for StyleBitz and we only hard code a single default number.

If you want to override the the TTARP number, there are a few ways to do this. First is our typical method that will set the number and cookie it allowing us to track visitors from unique landing pages. To do this, use the following ERB method in your view.

<% sb_ttarp_number_override_cookied '800-555-1234' %>

Please use the sb_ttarp_number_span in any content to generate the current TTARP number (default or override). This content tag will be updated by the cookied number above if set too allowing content pages to participate in conversion tracking. If you want to override the TTARP number for a single page without setting a cookie use this in your Rails view.

<% sb_ttarp_number_override '800-555-1234' %>

If you want to override the TTARP number independently of the marketing/conversion tracking initiative, use the following method to set TTARP numbers that neither set nor read from the ttarp_number cookie set by sb_ttarp_number_override_cookied. This should only be used in specific use cases as required (e.g. Fundraising requires specific service numbers regardless of the user's path through the site.)

<% sb_ttarp_number_override_local '800-555-1234' %>

Metrics Helper

By default the footer will load a combined JavaScript manifest of style_bitz/metrics.js. This file is a concatenation of all metric related JavaScript. This includes Interactions. It is possible to opt out of any to all of these. When doing so, StyleBitz will use distinct manifest/asset files vs the combined manifest only. For example, any combination of the 3 below are up to you. Remember, by default if all are on, you get one minified file.

<% sb_interactions_off! %>

Messaging Helper

This helper allows easy construction of alert and dialog components. Each helper takes a type argument and an optional block to render message content. Please read the components documentation each component's supported type.

<%= sb_alert :success do %>
  <p>Login Successful!</p>
<% end %>

<%= sb_dialog :success do %>
  <h4>Account preferences updated!</h4>
<% end %>

Both alert and dialog components have a JavaScript interface for working with them. This is supported by the Rails helpers too. Using either the sb_alert or sb_dialog helper with no arguments creates an empty (and hidden) component that can be populated via the JavaScript interfaces.

<%= sb_alert %>
<%= sb_dialog %>

The JavaScript singletons objects are smart enough to instantiate themselves to an existing fully rendered alert or dialog box too. For example, you could render an sb_dialog(:error) { ... } block as seen in the first example on page load and that UI component can respond changes via the StyleBitz.Dialog singleton. Use the method that best works for you.

Service Hours Helper

We provide service hours in two formats, :long and :short. Use the sb_service_hours(format) helper to return an array of each of the hour strings ordered by Mon-Fri, Sat, and Sun. For example, here is a simple way to get a sentence format for the :short format.

<%= sb_service_hours(:short).to_sentence %>

JavaScript Assets

Please read the StyleBitz & JavaScript section for full details.

Capybara Testing

The capybara DSL methods for checkboxes and radio buttons will not work out of the box for StyleBitz.

choose('A Radio Button')
check('A Checkbox')
uncheck('A Checkbox')

This is due to how we wrap our input elements with our label elements. To work around this we have created a StyleBitz::CapybaraHelper to mix into your integration tests.

sb_choose  'A Radio Button'
sb_check   'A Checkbox'
sb_uncheck 'A Checkbox'

These helpers use the same locator and options arguments supported by capybara's native counterparts.

Demo Pages

Here are a few pages to show full-stack usage of StyleBitz and Rails. The first page is a sandbox that you can play with. It is a basic content page. Feel free to play with the sandbox.scss file that imports StyleBitz core! Then add your HTML to sandbox.html.erb too.

Sandbox Page

The sandbox page was added to SiteContent too as a way of showing how StyleBitz works in that application. It is a perfect example of how to build top level CSS and JS manifests.

View Sandbox Page View Sandbox Page (condensed)

CustomInk Difference Page

The CustomInk Difference page shows a textually content heavy page. It has a navigation sidebar that is only visible on lg and higher breakpoints. This page leverages the content image responsive image component, responsive buttons links with margins, and the .sb-ListNav component. See the cidiff classes in the demo.scss file.

This page uses the oversized image and high compression ratio method for responsive images.

View CustomInk Difference Page

Accounts Page

The Accounts page shows a form heavy page. This page leverages form components and buttons.

View Accounts Page

St. Patrick's Day Page

The St. Patrick's Day is an example of a site content NSO landing page. When looking at the demo Sass file, pay close attention to the list of great SiteContent Components that could be re-used across various NSO pages. We have examples for a simple thin CSS rule, to complex template gallery and event lists.

IMPORTANT: Please do not use duplicate HTML content when designing any responsive page. Avoid the templation to use copied sections of HTML with different DOM layouts and then hide/show that at different breakpoints. Although it sounds useful, this is not a good practice from both a technical standpoint but does not asist a good content strategy. More important it is not good for SEO either.

View St. Patrick's Day Page