Sakai 3 UX Development Guidelines and Information

Added by Oszkar Nagy, last edited by Christian Vuerings on Feb 05, 2010  (view change)
Warning

Document work in progress!

Introduction


The main problem with guidelines and best practices is that they tend to get very long and very boring. Also there are an awful lot of them. My aim here is to communicate the most important things as shortly as possible and linking to existing guidelines or standards for developers who need more detail.

The other intent of this document is to serve as a reference point for evaluating UX patches. The current UX code does not conform to all of these guidelines (it is not very very far), but I think setting out to converge towards a clear set of standards and quality would be good.

I gathered all the resources which I could find, but a lot of this might not be properly credited, so if you see anything here which is definitely your idea please let me know.


General development aims and guidelines:


If this whole document could be compressed into one sentence it would go something like this:
Always try to create simple things which are easy to understand for the audience and other developers, following established open standards and are as accessible as possible.

General guidelines
  • HTML is valid XHTML 1.0 Transitional
  • CSS is cross-browser, arranged in logical blocks
  • Javascript passes JsLint validation and is unobtrusive
  • HTML container tags, Javascript functions, and CSS blocks are always well documented
  • Code does its best to be accessible
  • Markup and code is easily readable, with ample white space
  • Always aim for as less requests as possible
  • If there is a design for a certain element or feature, as a developer you should respect it as there might be a great deal of research and work in one single design, but everybody is more than welcome to contribute to the design process as a separate activity


Browser compatibility

All front-end should be tested and work on all of the following browsers:

  • Firefox 3 and newer on Windows/OSX/Linux (everything should be 100% functional on Firefox 2, but visual fidelity can gracefully degrade)
  • Internet Explorer 7 and newer on Windows (everything should be 100% functional on IE6, but visual fidelity can gracefully degrade)
  • Safari 3 and newer on OSX/Windows (everything should be 100% functional on Safari 2, but visual fidelity can gracefully degrade)

A good effort should be made for everything to work in Google Chrome and Opera.

Naming conventions for source files
  • File names should use lower case characters, without spaces.
  • Always use English alphanumerical characters and "." (dot) only in file names

Indentation / File encoding / Line endings in source files

Indentation: use spaces ( 4 ) for indentation, and make sure there are no trailing spaces after a code line
File encoding: UTF-8
Line endings: Unix line endings (\n)


Language specific guidelines:


HTML


Main Guideline

HTML should be well formatted valid XHTML 1.0 Transitional, and should pass W3C validation

HTML files generally should be stored directly in the root folder, (with some exceptions like overriding skin HTML for example)

A good set of guidelines which go into more detail can be found here:
BBC Semantic Markup Guidelines



HTML Documentation

All HTML markup should have comments for all of the containers regarding what they hold, especially for those ones which are empty, and filled later or dynamically, and it is good practice to comment the closing tag of the container as well, as it helps readability

Here is an example of well documented HTML:

<body>

<!-- MAIN CONTAINER -->
<div id="main_container">

	<!-- TOP NAVIGATION -->
	<div id="top_nav">

		<ul id="top_nav_list">
			<li>Home</li>
			<li>People</li>
			<li>Dogs</li>
		</ul>

	</div>

 	<!-- PAGE CONTENT -->
 	<div id="content">

		<!-- LIST OF PEOPLE - holder, filled dynamically -->
		<div id="people_list"></div>

		<!-- BIO - holder, filled dynamically-->
		<div id="bio"></div>

	</div>

	<!-- FOOTER -->
	<div id="footer">
		<p id="footer_content">Footer Content</p>
	</div>

</div>

</body>



HTML Best Practices

All inline styling should be moved to external CSS files, the only allowed styling should be style="display: none;"

Avoid using the <br /> element for styling or adding space in markup. Use CSS padding instead.

HTML should be indented according to the nesting of the tags (please see the example for documentation)

Use lower case characters and "_" (underscore) only for HTML ids (no leading underscore):
<div id="main_container"></div>


CSS


Main Guideline

CSS code should be cross-browser, avoiding browser dependent hacks and rules, and should be organized into logical blocks in relation with the markup which they affect. There are many ways of organizing CSS code, and there is no perfect one, but the guide here should be that there must be in some logical order.

CSS file names should follow the HTML or widget page name with "sakai" at the beginning: search.html --> sakai.search.css

Here are 2 common organizational patterns you can follow:

  • CSS structure following the structure of HTML (most of our CSS is organised this way at the moment)
  • Functional division: Layout, Typography, Colors etc...

Main CSS files (sakai.base.css) should not be modified for a new feature, page or widget, instead use a separate file. If the code becomes a pattern throughout the UX it can be moved to a base CSS file. A base CSS modification should always be proceeded by a pattern design change.

CSS Documentation

It is not necessary to document every single rule in the CSS file, but documenting and visually separating blocks of code is a good practice. In addition, The styles inside each block code should be alphabetical order.

An example of well documented CSS:

/** CONTAINER **/
.fixed-container
{ background: #fff; }


/** HEADING **/
.profile_preview .site_heading
{ color: #454a4f; padding: 10px 0; border: none; }


/** TABS **/
.profile_preview .primary-tabs
{ background: #fff url('../../_images/profile_tab_bg.png') top right no-repeat; height: 25px; border: none;  padding: 3px 10px 0 0; display: block; }

.profile_preview .primary-tabs ul
{ padding: 0; margin: 0; border-bottom: none; float: right; }

.profile_preview .primary-tabs ul li
{ margin: 0; padding: 0; background: transparent; border: none; display: block; float: left; }


/** TAB CONTENTS **/
.profile_preview .profile_container
{ padding: 0; margin: 0 0 20px 0; color: #454a4f; }


CSS Best Practices


All inline styling should be moved to external CSS files, the only allowed styling should be style="display:none;"

Avoid using the <br /> element for styling or adding space in markup. Use CSS padding instead.

Use CSS shortcuts/shorthands where possible:

.twitter_container {
    padding: 5px 10px;
}

instead of

.twitter_container {
    padding-top: 5px;
    padding-right: 10px;
    padding-bottom: 5px;
    padding-left: 10px;
}

Javascript


Main Guideline

The main JavaScript guidelines are well put together in Douglas Crockford's coding guidelines which can be found here:

http://javascript.crockford.com/code.html

Also all Javascript code should be validated by JSLint using the following settings:



Page Javascript files should be stored /_javascript folder
Javascript libraries should be stored in /_lib folder as a separate folder for each library. If a library uses CSS files those should be stored here as well.

License header

Every Javascript source file should contain the following license header:

/*
 * Licensed to the Sakai Foundation (SF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The SF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations under the License.
 */



Main Javascript libraries

At the moment (06 Nov, 2009) the following bigger Javascirpt libraries are used throughout the Sakai 3 UX code:

Javascript Documentation

All functions should be documented with a short description of what the function does, what are the arguments, and what it returns.

An example of good function documentation:

/**
* This function updates or sets the correct height of an iframe
* @param {String} ifrm - The iframe you would like to adjust
* @return void
*/
sakai.site.setIframeHeight = function(ifrm) {
 // function code here
}



Javascript Best Practices

Here is an already started best practices collection by Aaron, Christian etc, it contains quite a few entries:

http://confluence.sakaiproject.org/display/SAKDEV/Best Practices for Javascript


Additional best practices:

Widget Javascript code organisation:
0 License comment
1 Widget description comment
2 Globals
3 Config variables
4 Helper functions
5 Widget:
    5a Widget functionality functions
    5b Widget UI functions
    5c Widget events
6 Widget:
    6a Widget functionality functions
    6b Widget UI functions
    6c Widget events
7 Init
8 Any third party functions you might have, like jqModal etc...

Error messages

I would suggest to include the source (ie the widget name) in ALL of the error messages that is thrown by the widget and are system messages. Not the ones which are within an error div for input validation ("Please fill in the name field" etc.) but the ones which are system error messages ("Could not connect to server" in an alert()) So the error message would look like this, say from poll widget: alert("Poll Widget: Could not connect to server while trying to fetch the poll data!"); This would make it easier to deal with a problem later by instantly seeing which widget is screaming and where/what is the problem roughly.

Iteration

Iterating through arrays the following way can give around 30% speed bump as it doesn't use the expensive .length() in each iteration. 

// Faster iteration
for (var i = 0, j = my_array.length; i < j; i++) {
     /* do stuff */
}




UX Development process


Getting the code

The code can be downloaded by clicking on the Download button on:
http://github.com/oszkarnagy/3akai-ux

or by using Git and the following clone URL:
git://github.com/oszkarnagy/3akai-ux.git

Suggested development work-flow:

In general code management should be simple, so I would like to propose a similar work-flow which Ian is using for kernel development:

  • I will maintain a master branch available on the addresses above where I will merge all patches, after reviewing them.
  • All UX developers should fork my master, do development, commit often locally then push. When a developer pushed to his/her fork at Github, should send me a pull request.
  • I will go over the code, and merge it to my master branch if it does good things and doesn't break other people's code.

Initial setup:

  1. Make sure you have Git installed on your machine
  2. Get a Github account (not necessary, but makes your/my life easier)
  3. Fork my master branch on Github (http://github.com/oszkarnagy/3akai-ux), this will be the place where you put your patch.
  4. Clone your forked 3akai-ux repository to your local machine

Every day development:

  1. Make sure your local 3akai-ux master branch is up to date
  2. Make a new "dev" branch for your new dev work, and switch to it
  3. Do development
  4. Commit
  5. Do some more development
  6. Commit
  7. Switch back to your master branch
  8. Merge in your "dev" branch to your master
  9. push your master to your 3akai-ux fork on Github
  10. Send the technical lead a pull request, currently at http://github.com/oszkarnagy/3akai-ux in Github or at oszkar@caret.cam.ac.uk;

Bugs and new feature management

Bug and new feature management should happen on Sakai JIRA, within the 3akai space:
Sakai JIRA -> 3akai
If there is a bug or a new feature that needs to be implemented (as a design requirement) there should be a JIRA ticket for it with appropriate attributes ("New Feature Request", "Bug" etc...), where issue specific discussions can be held. If the issue needs wider discussion and coverage please use the UX mailing list: sakai-ux@collab.sakaiproject.org

Commit messages

Commit messages should be short but descriptive. It is good practice to include the JIRA ticket code in the commit message so that it easily relates to a specific bug or feature request:

Fixed overlapping buttons on Search page
SAKIII-256




Front-end Unit Tests



TO BE DISCUSSED AND FILLED LATER...


Kernel - front-end integration


Sources of information

If you are doing front-end development for Sakai 3, chances are high that you will need to familiarize yourself with the K2 Kernel services. A collection of documentation can be reached through the Kernel K2 Documentation page:
http://confluence.sakaiproject.org/display/KERNDOC/Kernel+-+K2+-+Documentation
 

Developing a new service

A lot of the times in order to realize a new design, new back-end services will need to be written. Here is a work flow which can be used to initiate a development cycle to develop a new service which is needed by a front-end developer in order to implement a feature required by the design:

As a front end developer:

  1. Create a specification for the service, by writing the first version of the documentation for the proposed service
  2. Post the specification on Sakai K2 JIRA
  3. Engage and discuss the service with a back end developer, making sure the specification for the new service is locked down and agreed by both parties before development begins

An example (not perfect) specification could look like this:

 [New service proposal] - RSS service
 
 Arguments:
  - feed_url: The URL of the RSS feed
  - page (default: 0): The current page number if pagination is required.
  - number_of_items (default: 10): The number of feed items displayed on a page
  - sort (default: date): "date" or "alphabet" - Specifies how the RSS entries are sorted
 
 Description:
 The RSS service takes a URL to an rss feed and if it's a correct feed, returns all the data it received from the feed.
 If it is not valid, it returns a 500 HTTP response code.
 If page argument is non-zero the service paginates the output and returns a "number_of_items" number of elements, from a page defined in the "page" argument.
 
 Output:
 The RSS feed in XML format


As a back-end developer:

  1. You should engage with front-end developers to make sure service proposals are technically viable, scalable and implementable before actually doing development by reading and modifying the specification if necessary.
  2. When a consensus is reached by discussing and modifying the specification, start implementation.


Accessibility guidelines


At the moment we don't have a good set of guidelines for accessibility, standards and legal requirements vary from country to country. This is something which needs looking at.

As an initial step, BBC has always taken the issue seriously and published a set of guidelines:
BBC Accessibility Guidelines

A more in-depth set of guidelines can be found at W3C's Content Accessibility Guidelines:
W3C Content Accessibility Guidelines

Short list of good accessibility practices
  • Always create and fill in the "alt" property of an <img> tag.
  • etc...

TO BE DISCUSSED FURTHER...




Localization guidelines


Although we have technical background for localization in Sakai 3 UX, the procedure and management of localization should be discussed further.
As an initial thought to kick this off the Wikimedia Foundation has a localization platform called translatewiki.net directly aimed at open source projects which might be a good way to deal with complexity.

TO BE DISCUSSED FURTHER...




Resources


If you are using a tool which makes development easier, why not let others know about it?

Development IDEs / Editors
Firefox web-development plug-ins
Version control
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.