Motivation
Below you find set of guidelines for developing Dashboard applications. Treat it as useful suggestions that can help you to develop a code that is consistent in look, feel and philosophy with other parts of our projects. Following this rules you will save your time and other developers time in future. This document was created as a result of several months of experimenting with different tools and libraries, fixing common bugs found in code, and a lot of effort was put to find the right tools suitable for Dashboard needs.
Theory behind it
There is one general rule for developing web applications that is superior to every single rule described below and from which everything below was developed. This rule is called
Progressive enhancement and you can read about it here:
http://en.wikipedia.org/wiki/Progressive_enhancement
Requirements for browsers and operating systems
In principle every dashboard application should be able to run without errors on browsers listed below:
- Internet Explorer 7+
- Firefox 2+
- Chrome
- Safari
- Opera
- Lynx (just a joke, but of course following progressive enhancement you can check how your app looks on lynx)
That also means it should execute correct on the following operating systems:
- M$ Windows
- Mac OS
- Linux
- Minix (another lame joke)
We also suggest you to use Scientific Linux CERN 5 as your primary OS and Firefox as your primary browser during web development. Choosing SLC 5 will save your time with installing many libraries that have to be installed to use dashboard development framework. Firefox is the most popular browser for our users (yes, we have great users) and you can install many useful extensions, listed below.
Software Tools
If you want to be effective during debugging web application you have to use smart enough tools that will help you with this not-very-trivial activity. Below is the list of useful tools, you should be already familiar with at least some of them:
- firebug
- powerful web development tool (you can watch small presentation here
)
- YSlow
- analyzes web pages and why they're slow based on Yahoo!'s rules for high performance web sites.
- webdeveloper toolkit
- Firefox add-one
- Visual Event
- with this tool you can view the event handlers which are attached to the document elements.
- Design
- adds grid, rulers, crosshair and some measurements to the website you are viewing
- mesureit
- other Firefox add-one, draw a ruler across any web page to check the width, height, or alignment of page elements in pixels.
- colorzilla
- yet another Firefox add-one, Advanced Eyedropper, Color Picker, Page Zoomer and other colorful goodies...
Libraries
General rule here is that you should
use jQuery
library for every low level activities like:
- DOM manipulation
- Event handling
- Ajax requests
But why?
jQuery is cross browser and mature JavaScript library. You don't have to care about differences in DOM model in different browsers or use low level JavaScript functions.
jQuery is fast, lightweight and has built-in very efficient and elegant DOM
selection system
. It is very stable, bug-free and supported by strong community and big companies like Google. Last but not least it is open source.
In particular try NOT TO USE these libraries:
- dojo
- prototype
- scriptacolous
- mootools
- glow
- extJS
It's nothing personal, we think they are awesome but there is
nothing
that couldn't be achieved using
jQuery. And we have just to choose something. You can also read a
presentation describing it in more detail.
All we want is to just get the best parts of software available

.
But I'm new to jQuery...
So give yourself 5 minutes reading
this
and you are not newbie anymore.
GUI
A small portion of theory here - although this could be hard to achieve when developing new GUI component form scratch you should keep in mind that good designed widget should be
aria
compliant.
GUI components
For developing user interface widgets we strongly recommend to use
jQueryUI
library. If you are not familiar with it we strongly suggest you to read this comprehensive
component overview
But why?
Basing on the previous, more general suggestion to use
jQuery as primary JavaScript library, using
jQueryUI seems to be a natural conclusion.
jQueryUI provides rich set of ready-made components that are well designed and highly customizable. What is more with
jQueryUI you don't have to worry about styling your components to make them looking consistent with other widgets thanks to
theming
that is fully supported by every
jQueryUI widget. You can read more about it here:
http://jqueryui.com/docs/Theming/API
Other GUI components
Unfortunately
jQueryUI in most cases won't cover all our needs regarding user interface (but jQueryUI team is working on many new components so it's good to check from time to time their
labs
). So below is a short list of other useful
jQuery plugins - most of them support theming.
to get rid of arrows added by the browser and:
span.ui-spinner
{
position:absolute;
}
due to bug in this spinner impelentation
- Context Menu
- a context menu plugin for jQuery. Demo here
.
- table sorter
- extremely easy to use plugin for turning a standard HTML table with THEAD and TBODY tags into a sortable table without page refreshes. Lightweight and good for sorting small tables on client side. Very useful. Unfortunately does not support theming out of box.
- scrollable table plugin
- converts a properly formatted table, having thead and tbody elements (tfoot optional), into a scrollable table.
- colorpicker
- this may be quite supprising but there is no good colorpicker plugin for jQuery yet. This is the best, thought it has horrible API (list with picker instances is a nightmare). The ideal case would be to implement something like this
or that
- timepicker plugin
- with jQueryUI you have only date picker. This Timepicker is nice as it uses sliders for setting the time and can be easly combined with datepicker. Theming is supported.
- custom checkboxes and radio buttons
- full article here
- This plugin is not very good because it requires divs wrapping checkboxes and doesn't work on jQueryUI dialog windows. JQueryUI team is working on better solution
- with good API, requring only checkbox itself but it have a problem with handling events (sometimes it catch click event, sometimes not). Currently the best solution is this one
because it works but not everyone likes this particular look and feel.
- get url param
- tool for extracting parameters from url
- fast and lightweight syntax highlighter
Themes
If we agree we are using
jQueryUI with it's styling capabilities, we should also agree on some particular theme to use along all pages. As this is only a matter of taste, just for definiteness - let's say default theme is
redmond (you can check how it looks and compare it to others here:
http://jqueryui.com/themeroller/
).
jQuery "helper" plugins
jQuery has entire set of plugins that can handle various needs, here is the short list of that we found useful:
*
jquery.color
Color manipulation library. Useful for converting from HSB to RGB (or reverse), from HTML color name standards, mixing colors and more.
- jquery.hotkeys
jQuery Hotkeys lets you watch for keyboard events anywhere in your code supporting almost any key combination. Read article and see the demo here
.
- jquery.base64
- Allows you to use base64 encoding on the client<->server data flow. Especially useful for sending user defined strings to the server (eg. text-based data filters).
- jquery.json
- allows to handle json outside ajax request.
Other "helper" libraries
- underscore.js
provides functional programming support: map, select, invoke, ... and a number of useful utility functions beyond that provided by jQuery.
- history.js
provides an implementation of the HTML5 history API: history.pushState and history.replaceState functions, as well as the window.onpopstate event. Browsers that already support his event (Chrome & Safari, Firefox 4+) use native implementations, which are able to change the page URL without refreshing the page. Older browsers use location.hash in order to mimic the official behavior. (Meybe it's a better equivalent of the history tool mentioned below).
- implementation of natural sort algorithm
Handling Forms
This is very subtle and complicated issue, which involves:
- validation on client side - for user comfort
- validation on server side - for security reasons
- ajax requests - for providing flexible API
- unified server errors and messages handling for debugging and application responsiveness
This is why there is a separate article about
FormHandling.
Plotting
Plotting is something completely different then User Interface components. To do plotting in robust way you have to get something you can paint on. The libraries that we are using more or less support the following:
- fetching data as ajax request from server
- client side drawing
- saving as image
- interactivity and animations
- cross browser support
- very good designed API and comprehensive documentation
In general you should consider using one of the following javascript plotting libraries, choosing one of them should be well thought based on requirements and/or code uniformity (eg. if you are using jQuery, which you probably should, if possible use jQuery plugin).
InfoVis, raphaeljs and graphael
JavaScript InfoVis Toolkit
is one of the best plotting libraries. It maybe handy if you need to display data in not very common manner such as treemap, space tree and few others.
Other plotting libraries that we recommend are
raphaeljs
and
graphael
.
You can find more info on InfoVis, raphaeljs and graphael inside the
presentation.
Flot
Flot
is a jQuery plugin that handles quite good in drawing common plots. It provides quite large level of interactivity but lacks a little bit in documentation.
Highcharts
Highcharts
is one of the most feature rich javascript plotting library. It works as a plugin to few common javascript frameworks including jQuery. Highcharts provides:
- Quite nice documentation with nice object view
- Easy to implement exporting options (exports to: png, jpg, pdf, svg) and easy printing
- Very neat looks and animation
- Good interactivity level
Grid
Although displaying tabular data can be treated like just another GUI task it is so sophisticated that requires separate set of tools. That's why there was no grid component for jQueryUI in first versions of this library but this is very important feature and is planned to be add (
grid component roadmap
). Meanwhile we found that
datatables
component is the best for our needs mainly because:
- it follows progressive enhancement concept
- it is build on jquery
- supports theming
- it's very easy to configure and customize
- supports server side processing and ajax requests
- handles rowspans in headers
- is very good documented and has very good online support
For simple tables you should use
grid markup
.
Comprehensive grid libraries overview you can find
here
.
Other useful JavaScript libraries
- mathjax
- an open source JavaScript display engine for mathematics that works in all modern browsers.
- Datejs
- an open-source JavaScript Date Library.
- ZeroClipboard
- The Zero Clipboard library provides an easy way to copy text to the clipboard using an invisible Adobe Flash movie, and a JavaScript interface.
- box2dweb
- 2D rigid body physics engine
Model View Controller
Model View Controller is one on most important design patterns when it comes to User Interface. Every sophisticated UI should implement that pattern. There is separate
article on implementing MVC in dashboard framework. Here we will only mention libraries that help with implementation:
- backbone.js
- supplies structure to JavaScript-heavy applications by providing models with key-value binding and custom events, collections with a rich API of enumerable functions, views with declarative event handling, and connects it all to your existing application over a RESTful JSON interface.
- jquery.ba-bbq
- Enables you to activate back button in your ajax based applications as well as building bookmarking capabilities. It also provides advanced url search and hash support.
This two libraries combined, enable to create very complicated UIs and store their state. User benefits from this because he can treat "back" button i browser just like a "undo" button in desktop application. Also he can send a link to the specific state of the app to have other user see exactly the same view.
Other Architectual Components
Building large scale JavaScript application is not only about UI components, tools, libraries, and MVC. It's much more and dashboard framework is in the middle of the process of incorporating all important pieces and putting them together. Although having all these pieces in our framework is still a future there is always a need to use them. This is why you may find helpful
this presentation describing in detail all of the important parts.
Dashboard framework - implementation state
hBrowse framework
The hBrowse Framework is a new kind of generic open source monitoring application. It's a html/javascript client that can be combined with any kind of server as long as it can send json formatted data. Whole application can be setup using just one settings file.
The hBrowse framework is a generic monitoring tool designed to meet the needs of various communities connected to grid computing. It is strongly configurable and easy to adjust and implement accordingly to a specific community needs. Each part of this software (dynamic tables, user selection etc.) is in fact a separate plugin which can be used separately from the main application. It was especially designed to meet the requirements of Atlas and CMS users as well as to use it as a bulked Ganga monitoring tool.
Download and documentation
Main Features
- Highly configurable environment
- Bookmarking support
- History support
- Easy search
- Google charts support
- Highcharts support
- Independent View (Client)
- ... and many more
Example usecases
Coding Style and Validators
General
Try to keep JavaScript, CSS, and XML in separate files. Do not inline JavaScript or CSS in XML.
But why?
You are not developing a wbesite for your friends. You are developing application. When application grows it's harder to maintain mixed code. Also It's easier to find code repetitions in pure
JavaScript files and merge it into one file or event create library or jQuery plugin.
JavaScript
Just try to read and follow
Google JavaScript Style Guide
- don't embed event objects (i.e. onclick, onkeydown etc.) into HTML tags like:
<a onclick="..." />
Use jQuery selectors instead: $('a').click(...);
and place them into separete js files.
- don't use
alert(...);
- it's blocking whole browser and annoing users, use apprise
instead
- validate your JavaScript using jslint
- in some cases it would be better to evaluate code using jshint
- for sharing JavaScript with instant ability to evaluate, validate (using jslint) against many JS libraries jsFiddle
can be used.
Learning JavaScript
For learing JavaScript we've found some high quality resources:
Other useful resources
Besides books and tutorials there are some daily blogs with news about new JavaScript libraries and thechnologies. It alway woth checking them first before implementing some featers to aviod reinventing the wheel.
- dailyjs
- Daily updated JavaScript blog
- Addy Osmani blog
- very useful blog with many tutorials, screencasts, presentations, slides and other resources bout JavaScript.
CSS
Several things to mention here:
- try not to use styles embedded in html tags - all css should be put in external css files.
- validate your css using css validator
- try to read and get familiar with list of bugs for IE6
, IE7
and IE8
and try to make some conclusions what styles not to use or how to predict some possible bugs.
HTML
Here just a few things:
Python
You can use
pychecker
to verify that there are no security violations in your code
Just a few minor things found in code:
- do not use tabs. Make sure that your editor converts them to spaces.
- do not use
X.has_key(Y)
construct, use Y in X
instead (has_key is deprecated according to documentation
.)
JSON