My name is Adam Chambers, I’m a senior engineer at Digital Surgeons and a lead developer on our open source project Gumby Framework.

In this tutorial I’m going to take you through the process of installation and configuration of a Gumby project and then put together a simple web page.

First off I’d like to apologise for my hilarious colleague and fellow Gumby lead dev, Craig Keller. His passion and admiration for my nationality and all things English never fails to amaze me, hence this (slightly patronising) design we’re going to build.

Anyway, disclaimers aside, lets dive in.

Here’s what we’re going to build in it’s finished state:



View the Demo

Gumby is a responsive front end framework built on Sass and Compass. Along with the release of Gumby 2.5 we launched Claymate, an NPM module that interfaces with Bower and Uglify to assist in the installation and optimisation of Gumby. Because of this there are a number prerequisites for getting started. It would be out of the scope of this tutorial to explain the installation of each of these dependencies, however there is a load of information out there so I’m going to assume you have the latest versions and a basic understanding of the following: Ruby, Sass, Compass, Node.js, Bower & Git.

Installation

Claymate currently has two functions, installation and optimisation. We’ll cover optimisation later but for now lets setup our Gumby project. With one simple command Claymate will install Gumby and set up a basic project scaffold.

# install Claymate globally via npm $ npm install -g claymate # bootstrap Gumby project $ claymate install

You can read more on Claymate installation in our documentation but for the purpose of this tutorial we’ll use an example git repository so we can jump back and forth between the stages that make up a Gumby build.

# create and cd into project directory $ mkdir gumby-tutorial $ cd gumby-tutorial # clone the tutorial git repo and checkout step 1 $ git clone [email protected]:GumbyFramework/Tutorial.git $ git checkout step-1

Now take a look at the directory structure here.

├── bower_components/ │ └── gumby/ ├── css/ │ └── gumby.css ├── fonts/ │ └── icons/ │ ├── entypo.eot │ ├── entypo.ttf │ └── entypo.woff ├── img/ ├── sass/ │ ├── var/ │ │ └── _settings.scss │ ├── _custom.scss │ ├── _fonts.scss │ └── gumby.scss ├── config.rb ├── gumby.json ├── index.html └── ui.html

This is what you would see after running $ claymate install . A number of things have happened here in order to bootstrap your Gumby project so lets go through it in detail.

Firstly, Gumby has been installed using the awesome tool that is Bower. You’ll find a full build of the framework in the bower_components directory, as if you had directly cloned Gumby’s GitHub repo. Bower allows you to install, update and manage your front end dependencies; With a simple command you can update your dependencies to the latest releases. This means the bower_components directory should remain untouched so nothing is overwritten. This, however, presents a problem.

We encourage Gumby users to edit the variables in settings.scss in order to customize the framework to as close to ones requirements as possible before overwriting and extending Gumby. However, our changes would get overwritten if we updated to the latest Gumby. Luckily, Claymate provides a solution by copying the files that require editing out of the bower_components directory and into the root of your project.

You’ll notice sass , css , js , img and fonts directories along side config.rb , ui.html and index.html files. The fonts directory is a direct copy from Gumby and contains your icon font while the js / img directories are empty and there for your convenience.

Now here’s where the real magic has happened. Open up the sass directory and you’ll find various partials copied from Bower’s copy of Gumby. If you open gumby.scss in a text editor you’ll notice the original paths have been updated to point to the bower_components directory, except for _settings.scss and _fonts.scss which are pointing to the new copied files.

The only core files you should need to edit are _settings.scss and _fonts.scss , copying these files out of the bower_components directory allows you to work on top of Gumby rather than within. The only manual change you’d need to make when updating would be to copy any new variables into your _settings.scss copy.

This set up allows Bower to really flex it’s muscles when the time comes to update.

Take a look around this fresh installation and get a feel for how the file structure is set up and when you’re ready, checkout step 2 of the tutorial.

$ git checkout step-2

Configuration

As I said, _settings.scss is the only core Gumby file you need to edit, and herein lies Gumby’s real power. If you open the file, you’ll notice that since step 1 I have modified a load of the default variables.

Before I was ready to start building out any markup I had changed the grid width, number of columns, font face, header colours, navbar colours and primary/secondary colours. Building the basic theme of the site out like this allows developers and designers to really collaborate on the core styling before any markup or specific styles are written. We have found that this method of development drastically improves maintainability.

In fact, this is how we recommend you begin any development with Gumby. You can tweak settings variables to get the core theme of your project together, or at least as close as you can, before you begin to overwrite anything.

If you call the compass watch command from the root of your project, you can play with the settings variables and check out the results in ui.html . Mess around with the variables and and get a feel for how they are used throughout the framework. Once you’re ready, checkout step 3 of the tutorial (you’ll need to undo or commit any changes you made to move on).

$ git checkout step-3

Extensions

Ok, so now we have installed Gumby and configured the settings to get our build as close as possible to the site theme. Before we begin building out the site, we’re going to need to install a few more packages. Gumby Extensions, of which there are currently 4, are modules hosted in separate GitHub repositories and installed individually via Bower. We are going to utilise all four of these extensions in this design.

If you look in the project root you’ll see a new bower.json file and inside the bower_components directory there are now gumby-parallax , gumby-images , gumby-shuffle and gumby-fittext directories. These packages have all been installed using the $ bower install command.

# install all a package $ bower install --save gumby-parallax # update all packages $ bower update # update gumby parallax only $ bower update gumby-parallax

Once installed, these extensions needed to be imported into our Gumby project. Open up gumby.scss and you’ll see a new line I’ve added right before _custom.scss importing the parallax sass from bower_components . Once compass compile has been called, our css will contain the parallax styles.

@import "../bower_components/gumby-parallax/parallax";

Check out the bottom of index.html to see the new script tags. The parallax, images, shuffle and fittext JavaScript have been added with the other UI modules before gumby.init.js , this is the order in which Gumby JavaScript must be executed.

gumby.js -> modules -> gumby.init.js

<!-- Gumby and Gumby modules --> <script gumby-touch="js/libs" src="bower_components/gumby/js/libs/gumby.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.retina.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.fixed.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.skiplink.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.toggleswitch.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.checkbox.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.radiobtn.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.tabs.js"></script> <script src="bower_components/gumby/js/libs/ui/gumby.navbar.js"></script> <script src="bower_components/gumby/js/libs/ui/jquery.validation.js"></script> <!-- Gumby extensions --> <script src="bower_components/gumby-parallax/gumby.parallax.js"></script> <script src="bower_components/gumby-images/gumby.images.js"></script> <script src="bower_components/gumby-shuffle/gumby.shuffle.js"></script> <script src="bower_components/gumby-fittext/gumby.fittext.js"></script> <!-- Gumby Init --> <script src="bower_components/gumby/js/libs/gumby.init.js"></script>

Debug Mode

The last change I made in this step was to ]turn on Gumby’s debug mode. This is done by adding the gumby-debug attribute to the gumby.js script tag. When in debug mode, Gumby will log information to the console including module installations and event triggers. This can be a really useful tool during development. Open index.html in your browser (it will be blank). Then open up the console (alt + command + i in Chrome) and refresh to see Gumby’s debug info. You can use Gumby’s debugging methods throughout your own JavaScript if you wish.

<script gumby-debug gumby-touch="js/libs" src="bower_components/gumby/js/libs/gumby.js"></script> Gumby.debug('Print debug message to the console'); Gumby.info('Print information to the console'); Gumby.warn('Print warning to the console'); Gumby.error('Print error to the console');

Build

Ok, now it’s time to start building out the example site. Checkout step-4 to see the complete build and follow through the commit log on GitHub or, if you know your way around Git, checkout each commit to look around the code at that particular stage.

$ git checkout step-4

Markup

Firstly I built out the basic markup.

The grid is put together as columns inside rows – there’s no need for container elements unless you want them. Grid systems have been around for long enough so I’ll avoid going into too much detail here but we have .row , .columns , .centered , .push_x , and .pull_right and pull_left classes for you to play with. Most of which are used throughout this example project.

<div class="row"> <div class="seven columns"></div> <div class="four columns push_three"></div> </div>

Gumby’s settings file contains a number of color variables, several of which we edited for the example site. Each of these variables has a corresponding class that can be applied to a button, label, badge or alert. You’ll notice several buttons with pre-pended icons used throughout the design. These can be created with a few simple classes.

<p class="btn primary medium"><a href="#">Primary Medium Button</a></p> <p class="btn primary medium icon-left icon-location"><a href="#">Primary Medium Button</a></p>

Gumby’s responsive navigation is included at the top of the page complete with a dropdown menu. Check out how it responds – nice, huh? We’ll cover the logic behind the mobile navbar toggle later. If you inspect the logo <img> you’ll notice it has a gumby-retina attribute. In the same images directory we have a retina ready version of the image with @2x appended to the file name. Adding the gumby-retina attribute initialises Gumby’s retina module which will load the retina version on supporting devices.

Sass

Next I wrote some custom sass to style my markup and override a few Gumby defaults.

The details of the Sass could easily be a separate tutorial so I’ll be brief. However, there are a few Gumby mixins I’d like to pick up on.

Fancy Tiles

Fancy Tiles are used to style the footer links and are perhaps best described as a combination of Tiles and the Grid. If you find #foot-links in _custom.scss you’ll see the mixin in use.

/* scss */ @include fancytiles(8,8,4); /* compiles to */ @media only screen and (min-width: 320px) { #foot-links ul { width: 25%; } } @media only screen and (min-width: 768px) { #foot-links ul { width: 12.5%; } } @media only screen and (min-width: 1100px) { #foot-links ul { width: 12.5%; } }

The numeric arguments I’m passing to the mixin specify the number of columns per row I want at three predefined breakpoints, desktop, tablet and mobile. Resize the browser window and see how they respond accordingly. Fancy Tiles are awesome for fat footers like this, product grids and any dynamic website where the required number of rows and columns is unkown. No longer worry about opening and closing rows and save yourself a lot of time and stress!

Respond

Next up is a very important mixin in Gumby development. The respond mixin allows you to define responsive styles at a number of pre-defined breakpoints. Check out the full list of breakpoints in the mixin definition. Simply include the mixin, pass it the required breakpoint and insert your styles. Sass will convert these into ugly media queries when compiled.

/* scss */ @include respond(portrait-tablets) { background: red; } /* compiles to */ @media only screen and (max-width: 768px) { background: red; }

Font Size

Finally the font size mixin. The em is a great format but can be dificult to work with, we all like px right? Well the font-size() mixin makes the conversion for us. Simply pass in a px size or one of our pre-defined modular scale variables variables.

/* scss */ @include font-size(18px); /* compiles to */ font-size: 16px; font-size: 1.125em;

FitText

Here is where I first used one of Gumby’s extensions, in this case FitText. The FitText extension was modified from the awesome FitText.js jQuery plugin and serves to make font sizes flexible. Add the .fittext class to any element with optional gumby-rate and gumby-sizes attributes. The gumby-rate attribute works like FitTex.js’s Compressor and controls the rate at which the font size increases/decreases. The gumby-sizes attribute lets you specify a minimum and maxiumum font size separate by a pipe. Resize your browser and watch fittext do it’s thing.

<h2 class="fittext" gumby-rate="2" gumby-sizes="30|60">Traverse the time vortex with precision.</h2>

Fixed Positions

Next I applied the fixed position module to the navbar to make it ‘fix’ when it reaches the top of the viewport and ‘pin’ when it reaches the bottom of the masthead. Fixing and pinning like this is a common UI requirement and the fixed position module works as a kind of polyfil for the CSS3 property position: sticky; with some advanced functionality. This module is great for navigation, sidebars as seen in our documentation and many other UI features.

<!-- fix when top of viewport is reached pin when window scrolled 500px --> <div gumby-fixed="top" gumby-pin="500">My fixed content</div>

Skip Links

Skip links slide the window to a specific vertical point. They are quick and easy to set up and are utilised in various locations in this design. The navbar dropdown menu contains a set of skip links and the three featured images at the top of the content area also skip to sections of content. To initialise a skip link add a class of .skip to any element, although usually an anchor. All you need to do then is add a gumby-goto attribute containing either a px value, the string ‘top’ or a css selector and your skip link will take you there. You also have gumby-duration and gumby-easing (requires jQuery easing plugin) to play around with, so have some fun!

<!-- on click slide to #main --> <a href="#" class="skip" gumby-goto="#main">Skip to main</a>

Toggles & Switches

Toggles & Switches really require a dedicated tutorial. They are one of the coolest features of Gumby and really allow you to get creative and build UI elements without having to write a single line of JS. The basic idea is to add/remove css classes using HTML attributes, so that CSS transitions can be used to power UI aesthectics. We can avoid having to use :psuedo states or wasting JavaScript’s time toggling classes. Gumby comes with Modals and Drawers, both of which are examples of toggles & switches and are not dedicated UI modules with associated JS files.

Markup

In this design we use Gumby’s modal example of Toggles & Switches. First I added the modal markup. The modal is hidden by default with a negative z-index and opacity: 0; , these values are then overwritten when the .active class is applied.

<div class="modal" id="modal"> <div class="content"> <h1 class="row">Modal Markup</h1> </div> </div>

Switches

Next I added several switches to open the modal. The gumby-trigger attribute contains a selector targeting the modal element. Inside the modal I have two hidden divs of content. Different buttons and links should open the modal with the appropriate content displayed. To do this, the switch’s gumby-trigger attribute contains a selector that targets the modal itself and the content we want to display, with the content we want to hide specified after a pipe. Toggles & Switches will add a class of .active to the selector specified before the pipe and remove it from the selector specified after.

<a href="#" class="switch" gumby-trigger="#modal,#modal .get-quote|#modal .find-dealer">Get a quote</a>

You can get really advanced with Toggles and Switches once thir full potential is understood. I recommend reading our documentation and experimenting with the possiblities.

Parallax

The next extension I used was Parallax. I applied the parallax module to the masthead to quickly create a cool scrolling effect. The Parallax module modifies the background-position of the the element the .parallax class is applied to. It will scroll the background image relative to the window scroll at the rate specified in gumby-parallax .

<!-- scroll background image position at half the rate the window scrolls --> <div class="parallax" gumby-parallax="0.5"></div>

Shuffle

The Shuffle module provides an easy way manage source ordering. In this example I applied the shuffle module to the #highlights images, so that at tablet size the order reverses. This can be useful for ensuring your content appears above your sidebar when columns stack or moving calls to action and mobile specific features to the top of the page on smaller screens. The shuffle module requires a media query and a sequence specified in a gumby-shuffle attribtue, separated with a pipe. The sequence should be zero indexed, separated with a dash and represent the order the children elements should be shuffled to.

<!-- reverse order at 768px --> <div class="row" gumby-shuffle="only screen and (max-width: 768px) | 2-1-0"> <div class="four columns">...</div> <div class="four columns">...</div> <div class="four columns">...</div> </div>

JavaScript

Now it’s time for some JavaScript. Gumby has a load of events and advanced JavaScript features which we won’t go into in this tutorial, but for those who know JS, here’s a couple of simple-ish examples. I won’t be offended if you web designers skip past this section!

Initialisation

So first things first, I created a JavaScript file in the js directory and named it main.js . I then updated the path to main.js in index.html from Gumby’s example in bower_components to js/main.js . I then wrote the first lines of JS used in this project.

The shuffle module works by removing elements from the DOM, reordering and inserting again. Becuase of this, the skiplinks need initialising as if they were dynamically added to the web page. Gumby UI modules trigger and bind to many events that you can use in your custom JS. In this case we bind to the Shuffle module’s gumby.onShuffle event and call the Gumby.initialize() method to initialise new modules of a certain type. There are many events and variations on initialisation and I encourage you JavaScript nerds to check them out.

// Gumby is ready to go Gumby.ready(function() { // initialise new skiplinks when #highlights are shuffled $('#highlights').on('gumby.onShuffle', function() { Gumby.initialize('skiplink'); }); });

Validation

Next up I used Gumby’s Validation JQuery plugin to apply validation logic to the quote form in the modal. Call the jQuery plugin on any form element and pass it a ‘required’ property containing an array of required objects. Each required object should contain a ‘name’ matching an input’s name attribute within the form and an optional corresponding validate function. The validate function is passed the element itself as an argument and must return a boolean to indicate success or failure. If the validate function is ommitted the field will just be tested for a present value. Optional submit and fail callback functions can be specified, if ommitted the form will submit as usual when validation is passed.

$('.get-quote form').validation({ required: [ { name: 'name' }, { name: 'phone' }, { name: 'email', // email must contain @ validate: function($el) { return $el.val().indexOf('@') > -1; } }, { name: 'version', // must pick version with valid value validate: function($el) { return $el.val() !== '#'; } } ], // validation passed submit: function(formData) { Gumby.debug(formData); alert("Succes! Posting form..."); }, // validation failed fail: function() { alert("Form validation failed..."); } });

Optimisation

We’re all about performance at Gumby and have a number of performance based extensions coming to the framework in the near future. Claymate also has a build function to help in creating a single, optimised, production-ready JavaScript file. Check out step-5 to see the final optimisation stage of this example project.

$ git checkout step-5

Responsive Images

Media Queries

The responsive images module helps to serve up the most optimial image by file size or format.

In this example site I applied the responsive images module to the masthead to serve up a smaller background image to tablets. The gumby-media attribute can be set on any element with the syntax MEDIA QUERY | IMAGE PATH , it will refer to background images unless specified on an <img> . You can see here that we want bg_masthead-768.jpg to render should the associated media query evaluate to true, with a default image supplied in gumby-default .

<!-- serve up bg_masthead-768.jpg at < 768px viewport --> <div id="masthead" gumby-media="only screen and (min-width: 768px)|img/bg_masthead.jpg,only screen and (max-width: 768px)|img/bg_masthead-768.jpg">

Feature Detection

I also applied the responsive images module to two large images. In this instance I’m serving up images based on feature detection. The gumby-supports attribute can also be used on an any element and should use the syntax FEATURE | IMAGE PATH . The feature detection is passed directly to Modernizr so make sure your Modernizr build contains the tests you require. Webp is an awesome image format from Google I recommend you check out, however gumby-supports can be used with any feature detection supported by Modernizr e.g svg. You could even add your own tests.

<!-- if supported use webp image otherwise fallback to jpg --> <img gumby-default="img/img_tardis.jpg" gumby-supports="webp|img/img_tardis.webp" />

Build JS

Each JS module is a separate file. As explained earlier we recommend that you include the required modules separately in development. Just be sure gumby.js is included first and gumby.init.js is included last. In production, we recommend you minifiy and concatenate all your JavaScript down to a single optimised file.

Don’t worry, Claymate is here to help again! Claymate’s build function will create a single gumby.min.js file for you, containing the UI modules you require and any external modules and custom files you specify.

When we installed with claymate, a gumby.json file was generated. Simlar to bower.json , we can update this file to include the information Claymate needs so that we can call $ claymate build without any arguments. Check out gumby.json and you can see the specification for this project. The UI modules we’ve used, the extensions and also our main.js file are all in there. This will create a new gumby.min.js file inside your js directory containing all the code you need for your application to run.

Your project is now ready for launch!

Conclusion

That brings this tutorial to an end. We’ve covered installation using Claymate, configuration using Gumby’s settings files and Sass variables, building an example site with Gumby and production ready optimisation. I hope you found this useful, if you have any questions, our Google+ community is a good place to start. We have a thriving and growing community of Gumby developers ready to help and discuss responsive web design. I’d also encourage anyone who wants to contribute to check out our GitHub repositories and shoot us any pull requests or ideas for improvements or new functionality you may have. Finally follow me and Gumby on Twitter to keep up with the latest!