[[TOC]]
= Developer Guidelines =

=== Development Process ===

'''Requirements and Design:'''
 * [wiki:BluePrints BluePrints]

'''Testing:'''
 * [wiki:DeveloperGuidelinesTesting Testing]
  * TestCases - User Testing - List of things to test
=== 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]

=== Quality ===

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

=== Release Process ===

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

=== Other Resources ===

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

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

 * [wiki:Domain Understanding the Domain]

=== Mobile ===

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

== 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].

== Tutorial ==

This tutorial was given at !SahanaCamp 1.1 in Taiwan:
 * http://www.slideshare.net/AidIQ/sahana-introduction-to-the-code-v2
 * [wiki:DeveloperQuickstart]

=== Model ===
Defines databases in: {{{/models/module.py}}}

The Models are loaded 1st within Web2Py processing, before the controllers.[[BR]]
So you can import any global modules/set any global variables here.[[BR]]
The Models are imported in alphabetical order, so we load the files which other modules depend on 1st, hence naming them appropriately:[[BR]]{{{000_config.py}}}, {{{01_crud.py}}}, {{{02_pr.py}}}, {{{03_gis.py}}}, etc

=== Controller ===
Python functions in {{{/controllers/module.py}}} [[BR]]
e.g.
{{{
   def list_records():
       items = crud.select(table)
       return dict(items=items)
}}}    

=== View ===
HTML/Javascript templates in {{{/views/module/function.html}}}
 * these are normal HTML/JS files with the ability to add in Python code (e.g. variables) surrounded by brackets: {{ interpreted python here }}
 * there should be an .html file available for each function in the module (name normally being the same as the function)
 * these normally inherit from {{{views/layout.html}}} which also includes the !JavaScript from {{{views/*_ajax.html}}}
 * if there is no view defined then a default view will be displayed, which will show the values of all the data it can see, but not be formatted nicely

Static CSS/Javascript files are stored in {{{/static}}}

== 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/

The Module Pattern should be used to protect private variables:
 * http://yuiblog.com/blog/2007/06/12/module-pattern/
 * http://www.adequatelygood.com/2010/3/JavaScript-Module-Pattern-In-Depth

=== 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}}}

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

Need to remove the '@' from '@requires' in header of {{{/static/scripts/S3/jquery.form.js}}} as we need to compress this without the main file.

Our build process is based on the one used by !MapFish (which is built on the one used by !OpenLayers)
 * !MapFish (inc OL): https://trac.mapfish.org/trac/mapfish/wiki/HowToBuild (NOTE: link is broken)
 * !OpenLayers: http://trac.openlayers.org/wiki/Profiles 

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

!ToDo: Investigate using LabJS to download/execute scripts asynchronously:
 * http://labjs.com