[[TOC]]
= Developer Guide =
== Introduction ==
=== Understand the Sahana mission ===
Before you start on the Sahana project, understand clearly what the project is about and what it strives to accomplish. You can find most of this in the Sahana [http://www.sahanafoundation.org/overview Overview and objectives]

=== Join the Community ===
Sahana is developed and guided by a large community of people from around the world, with diverse expertise. As everyone is in different timezones, the heart of this community are the mailing lists, so it is important for you to join it and actively participate in the discussion.

Please join a suitable [http://wiki.sahanafoundation.org/doku.php?id=dev:mailing_list_policy mailing list] and we recommend you read the community mailing list [http://wiki.sahanafoundation.org/doku.php/dev:community_etiquette etiquette].

Apart from that you can find a lot of us on [http://www.sahanafoundation.org/chat #Sahana IRC Chat].
=== Install a Development Environment ===
  - see [wiki:InstallationGuidelinesDeveloper]

=== Python ===
Indentation matters (use 4 spaces instead of Tabs)
 * http://diveintopython.org/
 * http://openbookproject.net/thinkcs/python/english2e/
 * 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 turorial conversion course]).

Web2Py can work at several different levels of abstraction.[[BR]]
The !SahanaPy 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 official Manual v2)

Recommend using the CLI to try out code snippets in the Web2Py environment (gluon, Model):
{{{
python web2py.py -S sahana -M
}}}
==== 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]]{{{00_db.py}}}, {{{01_RESTlike_controller.py}}}, {{{02_pr.py}}}, {{{03_gis.py}}}

==== Controller ====
Python functions in {{{/controllers/module.py}}} [[BR]]
e.g.
{{{
   def list_records():
       items=t2.itemize(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 ===
 * 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/

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

=== Reserved Keywords ===
 * 'request' -> web2py internal use
 * 'key' as a db row name -> MySQL confuses it with internal keyword KEY
 * http://dev.mysql.com/doc/mysqld-version-reference/en/mysqld-version-reference-reservedwords-5-0.html
 * http://www.postgresql.org/docs/8.1/static/sql-keywords-appendix.html

== Developer Guidelines ==

 * WSGI likes print statements to go to {{{sys.stderr}}} not {{{sys.stdout}}}: http://code.google.com/p/modwsgi/wiki/DebuggingTechniques

 * [wiki:DeveloperGuidelinesS3Framework SahanaPy Framework: S3]
 * [wiki:DeveloperGuidelinesInternationalisation Internationalisation]
 * [wiki:DeveloperGuidelinesSahana2Migration Help for Developers Migrating from Sahana2]
 * [wiki:DeveloperGuidelinesNewModule How to add a new Module?]

 * [wiki:DeveloperGuidelinesBzr Using Bzr]

 * [wiki:DeveloperGuidelinesCSS CSS]
 * [wiki:DeveloperGuidelinesGIS GIS]
 * [wiki:DeveloperGuidelinesLibraries Libraries]
 * [wiki:DeveloperGuidelinesThemes Themes]
 * [wiki:DeveloperGuidelinesWebServices Web Services]

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

 * [wiki:DeveloperGuidelinesCodeConventions Code Conventions]

 * [wiki:DeveloperGuidelinesUsability Usability]
 * [wiki:DeveloperGuidelinesTesting Testing]
 * [wiki:DeveloperGuidelinesOptimisation Optimisation]
 * [wiki:DeveloperGuidelinesReleaseProcess Release Process]

 * [wiki:ucore S3 UltraCore]

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

[[TranslatedPages]]