[[TOC]]
= Developer Guide =
=== 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 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
}}}

Web2Py can be extended through [http://www.web2py.com/plugins Plugins] & also has a [http://web2pyslices.com recipes site].
==== 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 ===
 * 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 Sahana Eden Framework: S3]
  * [wiki:RESTController REST Controller]
   * [wiki:S3REST S3REST]
  * [wiki:S3XRC S3XRC]
 * [wiki:DeveloperGuidelinesInternationalisation Internationalisation]
 * [wiki:DeveloperGuidelinesSahana2Migration Help for Developers Migrating from Sahana PHP]
 * [wiki:DeveloperGuidelinesDjangoMigration Help for Developers Migrating from Django]
 * [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:DeveloperGuidelinesDataMigration Data Migration]
 * [wiki:DeveloperGuidelinesArchitecture Architecture]
 * [wiki:DeveloperGuidelinesDocumentation Documentation]

 * [wiki:DeveloperGuidelinesCodeConventions Code Conventions]

 * [wiki:DeveloperGuidelinesUsability Usability]
 * [wiki:DeveloperGuidelinesTesting Testing]
  * TestCases - User Testing - List of things to test
 * [wiki:DeveloperGuidelinesOptimisation Optimisation]
 * [wiki:DeveloperGuidelinesReleaseProcess Release Process]

 * [wiki:ucore S3 UltraCore]

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

[[TranslatedPages]]