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.
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.
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.
Common <head> via style_bitz/core/head partial.
Common header via style_bitz/core/header partial.
Yielded content within a <main class="sb-Main"> element.
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.
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%>
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:
A content for yield to :sb_page_toolbar_content in between the message and links.
Please see the core helpers for additional details to configure the page toolbar.
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:
A content for yield to :sb_head_pre at the very top. Use this for custom tags like title or meta content.
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.
There are 14 icon meta tags to fill in. Get some from SG mobile_phone.html.erb assets.
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.
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:
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.
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.
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.
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.
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:
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:
Feel free to use one or both approaches!
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.
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.
If you add a new helper module to StyleBitz, please follow these guidelines:
Avoid name conflicts and prefix all method names with sb_.
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.
A few advanced features of the core helper.
sb_layout - Call this at the end of a view to force the style_bitz/layouts/core layout.
sb_main_wrapped! - Call this in your view to add the sb-Wrapper class to StyleBitz main element.
sb_main_content! - Call this in your view to add the sb-Main--content modifier class to StyleBitz main element. This sets up a responsive content area that has an appropriate top padding which is 1rem mobile first and 1.5rem at the lg breakpoint.
sb_set_main_classes - You can add your own classes to the sb-Main element by passing them to this helper. Useful when needing to scope your UI components from different pages. Do not use this to style sb-Main!
sb_toolbar_message_hide! - To hide the message in the page toolbar.
sb_toolbar_links_hide! - To hide the links in the page toolbar.
sb_header_condensed! - Call this in your view to add sb-Header--condensed to the header and remove all menus from the DOM.
sb_footer_condensed! - Call this in your view to add sb-Footer--condensed to the footer and remove a lot of content.
sb_header_ttarp_hidden! - Call this in your view to hide the ttarp section of the header. For an example, see demo page. FYI this method is deprecated!
sb_footer_coda_nav_force! - Call this to force the condensed footer to show site navigation links. Good for search pages.
sb_layout_condensed! - Use this to call the previous two condensed helpers.
sb_minimal_ui! - Force the page to 100% height. Use this when you have bottom buttons/CTAs and need minimal UI behavior.
sb_indexing_off! - Call this to stop robots from indexing your page.
sb_crawling_off! - Call this to stop robots from crawling your page.
sb_sticky_nav! - Call this to enable our sticky nav. Currently not compatible with TurboLinks, since the Catalog app and fulcrum app will most likely use its own contextual sticky nav as opposed to this more generic nav. This navigation will primarily be used on site_content and inkpress pages for the time being.
sb_sticky_nav_start_on(dom_classname) - Include this with the sticky nav, if you want to override the default behavior of the sticky nav starting to show when user scrolls to 'sb-Main'.
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.
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.
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.
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.)
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.
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.
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.
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.
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.
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-ListNavcomponent. See the cidiff classes in the demo.scss file.
This page uses the oversized image and high compression ratio method for responsive images.
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.