[[TOC]]
= Developer Guidelines =

== Development Process ==
 * [wiki:Domain Understanding the Domain]
 * [wiki:DeveloperGuidelines/Tutorial Tutorial]
 * [wiki:Projects]
 * '''[wiki:BluePrints BluePrints]'''

 * [wiki:DeveloperGuidelinesTesting Testing]
  * TestCases - User Testing - List of things to test

 * [wiki:DeveloperGuidelinesUsability Usability]
 * [wiki:DeveloperGuidelinesCodeConventions Code Conventions]

 * [wiki:DeveloperGuidelinesOptimisation Optimisation]

 * [wiki:DeveloperGuidelinesReleaseProcess Release Process]
  * [wiki:DeveloperGuidelinesDataMigration Data Migration]

 * [wiki:DeveloperGuidelinesUpdates Updates]

== Development Enviroment ==
 * [wiki:InstallationGuidelinesDeveloper How to install a Development Enviroment]
 * [wiki:DeveloperGuidelinesBzr Using Bzr] Version Control
  * [wiki:DeveloperGuidelinesBzr#HowtogetyourworkMergedintoTrunk How to get your work Merged into Trunk]

== Framework ==
 * [wiki:DeveloperGuidelinesS3Framework Sahana Eden Framework: S3]
  * [wiki:S3 S3 Developer Guide]

 * [wiki:DeveloperGuidelinesNewModule How to add a new Module?]

 * [wiki:DeveloperGuidelinesGIS GIS] - Mapping
 * [wiki:DeveloperGuidelinesSVG SVG] - Charts

 * [http://web2py.com/book Web2py Book]

 * [wiki:DeveloperGuidelinesSahana2Migration Help for Developers Migrating from Sahana PHP]
 * [wiki:DeveloperGuidelinesDjangoMigration Help for Developers Migrating from Django]

== User Interface ==
 * [wiki:DeveloperGuidelinesCSS CSS]
  * [wiki:DeveloperGuidelinesThemes Themes]

 * [wiki:DeveloperGuidelinesInternationalisation Internationalization]

== Other Resources ==

 * [wiki:DeveloperGuidelinesTips Tips] - useful links to explore

 * [wiki:DeveloperGuidelinesArchitecture Architecture]
 * [wiki:DeveloperGuidelinesDocumentation Documentation]

=== Python ===

Indentation matters (use 4 spaces instead of Tabs)
 * http://diveintopython.org
 * http://openbookproject.net/thinkcs/python/english2e/
 * http://software-carpentry.org
 * Python v2 documentation: http://docs.python.org/ (We are currently using v2.5 or v2.6.)
 * Style Guide: http://www.python.org/dev/peps/pep-0008/

 * lxml (XML I/O): http://codespeak.net/lxml/tutorial.html

More details at: DeveloperGuidelinesCodeConventions

=== Web2Py ===

This is an [http://en.wikipedia.org/wiki/Model-view-controller MVC] environment (like [http://web2py.com/AlterEgo/default/show/103 Rails] & [http://web2py.com/AlterEgo/default/show/101 Django]. [http://vimeo.com/6507384 Django polls tutorial conversion course]).

Web2Py can work at several different levels of abstraction.[[BR]]
The Sahana Eden framework (S3) is built on Web2Py's !Auth/Crud classes in {{{tools.py}}} (with some remnants of the older T2), however sometimes we need more control therefore need to drop down a level or two.[[BR]]
 * http://web2py.com/examples/default/docs (recommend the 'New Cookbook' as well as the [http://web2py.com/book official book])

Recommend using the CLI to try out code snippets in the Web2Py environment (gluon, Model):
{{{
python web2py.py -S eden -M
}}}

Can execute a controller to be able to access its functions using:
{{{
execfile("applications/eden/controllers/mycontroller.py", globals())
}}}

Web2Py can be extended through [http://www.web2py.com/plugins Plugins] & also has a [http://web2pyslices.com recipes site].

=== Javascript ===
 * W3Schools' basic JS: http://www.w3schools.com/js/

 * jQuery is used for client-side business logic (hiding fields, opening up tabs, etc):
  * Tutorial 1: http://docs.jquery.com/Tutorials:How_jQuery_Works
  * Tutorial 2: http://docs.jquery.com/Tutorials:Getting_Started_with_jQuery
  * Main reference: http://docs.jquery.com
  * We use some plugins: http://plugins.jquery.com
  * & some Widgets: http://jqueryui.com

 * ExtJS is used for some advanced widgets:
  * http://extjs.com/learn/Tutorial:Introduction_to_Ext_2.0
  * http://www.extjs.com/deploy/dev/examples/grid/row-editor.html
  * API: http://www.extjs.com/deploy/dev/docs/

 * S3 includes a cross-browser debug utility (only shows up when ?debug=1):
{{{
s3_debug('message', value);
}}}

All global variables should be in the S3 namespace:
 * http://yuiblog.com/blog/2006/06/01/global-domination/

Private variables should be protected, e.g. using the Module Pattern:
 * http://yuiblog.com/blog/2007/06/12/module-pattern/
 * http://www.adequatelygood.com/2010/3/JavaScript-Module-Pattern-In-Depth

Can test out the performance of different options to achieve a task using:
 * http://jsperf.com
==== Deployment ====

Browsers default to only downloading 2 files from the same origin at a time, so many files is very slow on high latency links.

We therefore consolidate into fewer, larger files when running in Production mode.

Since GIS is a specialised app which requires many files, it's JS is loaded separately when required.

The build script is {{{static/scripts/tools/build.sahana.py}}}

It needs to be run from the 'tools' folder.

There is also a convenience wrapper for Windows to run this & also move results into their respective locations: {{{static/scripts/tools/build.cmd}}}

You must have an internet connection to run the build script unless you have a local version of the Compiler.

Our build process is based on the one used by !OpenLayers
 * http://trac.openlayers.org/wiki/Profiles 

This uses Google's Closure compiler to compress the JS. This is done using their web service, however for !OpenLayers itself we need to download the jar file & place in the tools folder since this is over 1Mb:
 * http://closure-compiler.googlecode.com/files/compiler-latest.zip

!ToDo: Investigate using other options instead:
 * http://developer.yahoo.com/yui/compressor/
 * http://www.crowproductions.de/repos/main/public/packer/jspacker.py

!ToDo: Download/execute scripts asynchronously:
 * http://headjs.com/
 * http://labjs.com
 * http://requirejs.org 

=== Mobile ===
 * [wiki:MobileAndroid Android] - Developer Guidelines for the Android client

=== XSLT ===
 * [wiki:XsltTemplates XSLT] - Stylesheets for XML & JSON !Import/Export