Using the JavaScript framework

The GUI core module _javascript-helpers comes with some great things you can use in your project and a framework you can easily extend to fit your needs.

The DEBUG flag

The DEBUG flag determines whether we write debug messages to the console and can be toggled with GUI.DEBUG.

Switch DEBUG on with: GUI.DEBUG = true;
Switch DEBUG off with: GUI.DEBUG = false;

The DEBUGfilter array

The DEBUGfilter array can help you make sense of the shatter in DEBUG central. Each module that is using the Debugger is prefixed with it's name e.g. popovers: Popover button clicked. You can add this prefix to the GUI.DEBUGfilter array to only show debug messages from that very module.

Only show debug messages from collapsible: GUI.DEBUGfilter = ['collapsible'];
Only show debug messages from collapsible and alerts: GUI.DEBUGfilter = ['collapsible', 'alerts'];
Switch filtering off again: GUI.DEBUGfilter = [];

The Debounce method

Debouncing ensures that a function can only be called after passing an x amount of time of it's last call. This is important for performance and will make sure events that, by their nature, are called several times per second only execute after the bulk of it has passed to keep processing to a minimum. An example use-case would be when you add a listener to the resize event of the browser window. When the browser is then resized the event would fire many times during the resizing, executing your listener each time. Adding the debouncer to the event listener will ensure your listener will only fire after the resize is seemingly done. Read more here.

$(window).on('resize', GUI.debounce(YourFunction, 30) );

The method comes with three parameters: 
@param   func       [function]  Function to be executed
@param   wait       [integer]   Wait for next iteration for n in milliseconds
@param   immediate  [boolean]   Trigger the function on the leading edge [true], instead of the trailing [false]

The Throttle method

Throttling ensures that a function is only called an x amount of time within a timespan. Same as the debounce function, this is important for performance and will throttle a continues call of a function to a more sensible amount. An example use-case here would be the scroll event. While the browser scrolls it fires the scroll event for each pixel which results in a lot of processing if you attach some logic. By using the throttle method you limit the times the event is executing your function and free resources for the browser to spend somewhere else. Read more here.

$(window).on('resize', GUI.throttle(YourFunction, 30) );

The method comes with three parameters: 
@param   func       [function]  Function to be executed
@param   wait       [integer]   Run as much as possible without ever going more than once per [n in milliseconds] duration

The Debug method

In the GUI we use this method to debug our code and make sure everything runs as expected. You can call it with four different categories to make readability easier. report for default messages, error for error reports, interaction for user interactions, send for ajax requests and receive for data arrivals.

GUI.debugging( 'Your own debug message', 'report' );

The method comes with three parameters: 
@param   text  [string]  Text to be printed to debugger
@param   code  [string]  The urgency as a string: ['report', 'error', 'interaction', 'send', 'receive']

The jQuery plugin for trapping focus

We include one jQuery plugin for trapping focus. We use it to ensure a great accessibility experience in popups and dropdowns. Read about it here.

To trap focus inside an element, run: $(".js-your-selector").trap();

Extending the framework

You can use the javascript framework as a starting point and add your own module. See below an example of an empty module. Run this code after the GUI JavaScript. 

(function(GUI) {

	var module = {};
	//create an object to assign to GUI

	//------------------------------------------------------------------------
	// private function: module internal stuff
	//
	// @param   input1  [string]  Description of input1
	// @param   input2  [array]   Description of input2
	//
	// @return  [string]  Description of output
	//------------------------------------------------------------------------
	function dostuff( input1, input2 ) {
		App.debugging( 'YOURMODULE: Running dostuff with ' + input1, 'report' );

		// YOUR CODE
	}


	//------------------------------------------------------------------------
	// module init method
	//------------------------------------------------------------------------
	module.init = function() {
		GUI.debugging( 'YOURMODULE: Initiating', 'report' );

		dostuff( 'test', ['one', 'two'] ); //run private function

		GUI.YOURMODULE.yourmethod(); //run public method

		// YOUR CODE
	};


	//------------------------------------------------------------------------
	// another public method
	//------------------------------------------------------------------------
	module.yourmethod = function() {
		GUI.debugging( 'YOURMODULE: Running yourmethod', 'report' );

		// YOUR CODE
	};


	GUI.YOURMODULE = module;
	//add your code to the GUI. make sure you mind
	//the namespace that is already there.


	GUI.YOURMODULE.init();
	//run the modules init method

}(GUI));