= Developer Guidelines =
[[TOC]]

== Getting Started ==
 * [wiki:Domain Understanding the Domain]
 * [wiki:DeveloperGuidelines/Tutorial Tutorial]
 * [wiki:DeveloperGuidelines/FAQ FAQ]

== Development Process ==
 * [wiki:Projects]
 * '''[wiki:BluePrints BluePrints]'''

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

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

 * [wiki:DeveloperGuidelinesTips#Pythondebugging Debugging]

 * [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:DeveloperGuidelines/Git Using git] Version Control
  * [wiki:DeveloperGuidelines/Git#HowtogetyourworkMergedintoTrunk How to get your work Merged into Trunk]

== Framework ==
 * [wiki:DeveloperGuidelinesS3Framework Sahana Eden Framework: S3]
  * '''[wiki:S3 S3 API Guide]'''
  * [wiki:DeveloperGuidelines/Templates Templates]

 * [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] & 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.7.)
 * 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.

Although, note that iPhone 3.x cannot cache files larger than 15kb and in iPhone 4 the limit is 25kb. And this is the size before gzipping.

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 as a web2py script:
{{{
python web2py.py -S eden -M -R applications/eden/static/scripts/tools/build.sahana.py
}}}

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:
 * Projects/Advanced/Optimisation

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

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