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.

• jQuery UI Selectmenu - An ARIA-Accessible Plugin for Styling a Custom HTML Select Element, demo, more elaborate discussion. It soon will be a part of jQueryUI.
• flyout dropdow menu with jQuery theming support, demo is here. You may also want to see other kinds of dropdown menus here
• multiselect box - works in an unobtrusive fashion, by just turning html multiple select inputs into a sexier equivalent. There's no extra markup needed. The widget is styleable using theming.
• lkfw-jquery-tooltip - Tooltip jQuery plugin that allows to attache many tooltips at once with the custom content. Content can be taken from title attribute or defined on initialization.
• tipsy - plugin for creating a Facebook-like tooltips effect based on an anchor tag's title attribute. Highly costumizable, well behaving with good designed API (for example you don't have to specify tooltip text in tooltip constructor, text can be taken from html tag attributes, which is very helpful if you generate html using xsl templates).
• boxy - flexible, Facebook-style dialog box for jQuery with support for dragging and size tweening.
• pines - advanced notifications plugin
• block slider
• form validation engine
• another form validation plugin (much more robust)
• spinner for numeric fields add small arrows to the side and allows you to specify maximum, minimum, step etc. (this one is still under development but it will be a part of jQueryUI so keep an eye on this but currenty better solution is described below)
• spinner - works better than previous one, support theming but this is third-party library. Remember that in order to use it with webkit browsers you have to add in css:

                      input[type=number]::-webkit-inner-spin-button,
                      input[type=number]::-webkit-outer-spin-button
                      {
                          -webkit-appearance: none;
                          margin: 0;
                      }                    
    

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

Feature	Dashboard	Proposed technology
GUI Widgets		jQuery
MVC		Backbone.js
Pub / Sub		jQuery events
Browser state		jQuery BBQ
Storage		store.js
Templating		icanhaz.js
Feature detection		has.js
Script Loaders		head.js
Build process		YUI Compressor
Testing		Selenium, Qunit

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

• Official website

Main Features

• Highly configurable environment
• Bookmarking support
• History support
• Easy search
• Google charts support
• Highcharts support
• Independent View (Client)
• ... and many more

Example usecases

• Production Operators UI
• Interactive View

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:

• Eloquent JavaScript - excellent e-book
• JavaScript Garden
• wtfjs
• learning advanced JavaScript
• w3fools
• Mozilla Dev Center
• Essential JavaScript Design Patterns For Beginners
• Presentation from Douglas Crockford
• Other material from Crockfords site (especially the articles on "Private Members in JavaScript" and "Prototypal Inheritance in JavaScript")

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:

• never use hidden input fileds in forms. Why? Because hidden fields are hidden - forms are harder to debug and understand. Use our forms approach instead.
• never use default action in forms, use our forms approach instead.
• don't use stupid table layout. Use [[http://www.hotdesign.com/seybold/][box model layout] instead.
• validate your xhtml using validator (yes, we know that this is just output of xslt styles applied to xml but by validating output you can think what to change in styles to make this output correct)
• 

  caption text

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

• validate your JSON using jsonlint