The global Gumby object is where all the magic happens. It is defined in js/libs/gumby.js and is required by all UI modules (except jQuery plugins). The UI modules are stored as separate files in js/libs/ui and should be included after gumby.js at the bottom of your page. The final include should be gumby.init.js which takes care of initializing the modules included above, as well as calling AMD's define function. This means your single optimised gumby.min.js file can be loaded asynchronously by Require.js or another AMD loader. The customizer will concatenate and minimize the required code into js/libs/gumby.min.js. If you download the full package or clone from GitHub we recommend you do the same in production, ensuring the global Gumby definition is at the top of your single concatenated file, followed by the required modules and finally gumby.init.js.
Gumby requires jQuery 2.0 or 1.9.1 and Modernizr so make sure Modernizr is included in the <head> of your document and jQuery before Gumby at the bottom of the <body>. Check out the demo.html and ui.html templates for an example. We recommend you use a custom Modernizr build in production, we use touch detection for Gumby Tap events so make sure that's included.
<!-- First include gumby.js --> <script src="js/libs/gumby.js"></script> <!-- followed by the required UI modules --> <script src="js/libs/ui/gumby.checkbox.js"></script> <script src="js/libs/ui/gumby.radiobtn.js"></script> <!-- followed by gumby.init.js --> <script src="js/libs/gumby.init.js"></script> <!-- In production include a single concatenated and minimized gumby.min.js --> <!-- The customizer will provide you with this file --> <script src="js/libs/gumby.min.js"></script>
Gumby 2 JavaScript is designed to work in the background, bringing the UI kit to life automatically, without the need to write any extra JavaScript. Gumby broadcasts and listens for specific events that can be used to extend the default behaviour of UI modules. All custom events are namespaced with 'gumby' and jQuery's on() and trigger() methods make binding and triggering these events easy.
To improve performance in Gumby 2, we removed the delegation of all UI events to the document. This means dynamically generated UI modules need initializing, each UI module has an initalization key that can be passed to the Gumby.initialize method.
// initialize dynamic tabs
Gumby.initialize('tabs');
// listen for the tabs onChange event
$('#my-tabs').on('gumby.onChange', function() {
console.log('My tabs changed');
});
// programatically trigger toggle
$('#my-toggle').trigger('gumby.trigger');
To improve performance on mobile devices we have a nifty little solution for handling click/tap events. In gumby.init.js we use Modernizr.load to test for touch support, if found a customized build of jQuery Mobile is loaded which includes only the touch events and minified is a grand total of 6KB. Once this file has loaded we update the Gumby.click property from 'click' to 'tap'. The UI modules that bind to click events use the Gumby.click property instead of simply specifying 'click', this way touch enabled devices will use jQuery Mobile's tap event and receive a serious performance gain.
You can use this property to in your JS to bind to the tap event where supported with a click fallback.
// bind to the tap event where supported with a click fallback
$('#button').on(Gumby.click, function() {
var ev = Gumby.click === 'tap' ? 'tapped' : 'clicked';
alert('You '+ev+' me!');
});
Checkboxes provide three events you can listen to, onCheck and onUncheck are self explanatory and onChange, which is emitted when either event occurs. The events check and uncheck can be triggered to programatically interact with the checkbox.
// listen for checkbox state alterations
$('#checkbox').on('gumby.onCheck', function() {
console.log('Checkbox checked');
}).on('gumby.onUncheck', function() {
console.log('Checkbox unchecked');
}).on('gumby.onChange', function() {
console.log("Checkbox updated");
});
// check checkbox
$('#checkbox').trigger('gumby.check');
// initialize dynamically generated checkboxes
Gumby.initialize('checkboxes');
Radio buttons provide two events, onCheck is emitted when the radio button is checked and check can be used to programatically check the radio button.
// listen for radio button checked event
$('#radio-btn').on('gumby.onCheck', function() {
console.log('Radio button checked');
});
// check radio button
$('#radio-btn').trigger('gumby.check');
// initialize dynamically generated radio buttons
Gumby.initialize('radiobtns');
Similarly to radio buttons, tabs emit an onChange event when a new tab is set as well as listening for a set event to allow programatic tab setting.
Proin elit arcu, rutrum commodo, vehicula tempus, commodo a, risus. Curabitur nec arcu. Donec sollicitudin mi sit amet mauris. Nam elementum quam ullamcorper ante. Etiam aliquet massa et lorem. Mauris dapibus lacus auctor risus.
Morbi tincidunt, dui sit amet facilisis feugiat, odio metus gravida ante, ut pharetra massa metus id nunc. Duis scelerisque molestie turpis. Sed fringilla, massa eget luctus malesuada, metus eros molestie lectus, ut tempus eros massa ut dolor.
Mauris eleifend est et turpis. Duis id erat. Suspendisse potenti. Aliquam vulputate, pede vel vehicula accumsan, mi neque rutrum erat, eu congue orci lorem eget lorem. Vestibulum non ante. Class aptent taciti sociosqu ad litora.
// listen for tab change event
$('#tabs').on('gumby.onChange', function(e, index) {
console.log('Tab '+index+' set');
});
// set second tab (zero indexing)
$('#tabs').trigger('gumby.set', 1);
// initialize dynamically generated tabs
Gumby.initialize('tabs');
Elements using the fixed attribute will emit onFixed and onUnfixed events as they gain and lose their fixed positions. This can be useful for modifying styles when fixed positions are added and no doubt alter your perfect layouts. If you specify an unfix point, the onUnfixed event will pass the callback an integer to specify the reason for the event. 0 for scrolling up past the first fixed point and 1 for scrolling down past the unfix point.
View your browsers console, you should see a log each time the sidebar is fixed and unfixed.
// listen for radio button checked event
$('#my-element').on('gumby.onFixed', function() {
console.log('Element fixed');
}).on('gumby.onUnfixed', function(e, point) {
if(point === 0) {
console.log('Unfixed. Scrolled up past fix point');
} else if(point === 1) {
console.log('Unfixed. Scrolled down past unfix point');
}
});
// initialize dynamically generated fixed elements
Gumby.initialize('fixed');
Skip links provide two events, the onComplete event is emitted once a skip link animation is complete and the skip event provides a way to programatically trigger the skip link.
// listen for skip link complete event
$('#skip-link').on('gumby.onComplete', function() {
console.log('Skip link complete');
});
// trigger skip link
$('#skip-link').trigger('gumby.skip');
// initialize dynamically generated skip links
Gumby.initialize('skiplinks');
Toggles and Switches are handled by the same UI module and they both provide two events for extending functionality. The onTrigger event is emitted when a Toggle or Switch is triggered by a user, this interaction can change depending on the event defined in the gumby-on attribute. The trigger event can also be used to programatically trigger Toggles and Switches.
// listen to a toggle and switch onComplete event
$('#toggle,#switch').on('gumby.onTrigger', function() {
console.log('Toggle triggered');
});
// trigger a toggle and switch
$('#toggle,#switch').trigger('gumby.trigger');
// initialize dynamically generated toggles/switches
Gumby.initialize('toggles');
Gumby.initialize('switches');
The Retina UI module appends @2x to images with a gumby-retina attribute, on retina enabled devices if the high res image is available. An onRetina event is triggered once the high res image has been loaded and the image src swapped.
Check the console on a retina supported device. We're using gumby-retina on our logo.
// listen for an image swapping to high res retina version
$('#my-img').on('gumby.onRetina', function() {
console.log('Image is now high res');
});
Gumby.initialize('retina');
Gumby 2 includes a validation jQuery plugin. The aim of this plugin is to simplify validation without over-engineering and removing flexibility. It acts as a convenient way to organise your front end validation and interact with Gumby danger/success classes.
A function to be called onSubmit when the form passes all validation, a serialized object of form data will be passed to the callback function. If not set, or set to false, the form will be allowed to submit.
A function to be called onSubmit when the form fails validation.
An array of required field objects each of which must contain a ‘name’ property matching the form field it represents and an optional validate function. The validate function will be passed an object representing the form field element and should return a boolean indicating successful or failed validation. If omitted, validation will be tested simply on a value being present. Every field will be validated on blur except selects which will be validated on onChange and checkboxes / radio buttons which will be validated on gumby.onChange.
$('form').validation({
required: [
{
// name field needs to simply contain a value
name: 'name'
},
{
name : 'email',
// email must contain an @
validate : function($el) {
return $el.val().match('@') !== null;
}
},
{
name : 'radio',
// radio button must be checked
validate: function($el) {
return $el.is(':checked');
}
}
],
fail: function(failed) {
alert("Please fill out all the required fields");
},
submit: function(data) {
$.ajax({
url: 'do/something/with/data',
data: data,
success: function() {alert("Submitted");}
});
}
});
Gumby 2 JavaScript also provides several helper functions and debugging tools, all of which are housed within the global Gumby object.
Gumby.ready()
Similar to the well known jQuery.ready method, Gumby.ready accepts a callback function and waits until the document and all Gumby UI modules have fully loaded before running.
Gumby.touch()
This method is identical to Gumby.ready(), however the callback function is only run on touch enabled devices.
Gumby.oldie()
This method is identical to Gumby.ready(), however the callback function is only run on Internet Explorer <= version 8.
Gumby.debug()
This method returns an object containing an array of UI module information, useful for examining available events, as well as the oldie and $dom properties.
Gumby.$dom
The $dom property holds a cache of the document upon load. If you need the document in it’s original state.
Gumby.click
The click property will be set to 'tap' where touch events are supported otherwise falling back to 'click'. Use it in your click event handlers.
Gumby.isOldie
A boolean to indicate if the current client is Internet Explorer <= version 8. This saves you having to query the html class attribute.
Gumby.ready(function() {
// do something when Gumby and all UI modules are ready
});
Gumby.oldie(function() {
// do something when the document is ready on .oldie browsers
});
// if .oldie browser, let them know!
if(Gumby.isOldie) {
alert("Why you use oldie browser?!!");
}
// log Gumby debug object to console
console.log(Gumby.debug());
// log document cache
console.log(Gumby.$dom);
// bind to the tap event where supported with a click fallback
$('#button').on(Gumby.click, function() {
var ev = Gumby.click === 'tap' ? 'tapped' : 'clicked';
alert('You '+ev+' me!');
});