DeveloperGuidelinesTips

== Python ==
 -  Slow start
  - http://openbookproject.net/thinkcs/python/english2e/
 - Quick start
  - http://diveintopython.org/
 - v.Quick start!
  - Indentation matters (use 4 spaces instead of Tabs)
  - OOP - everything is an object

== Web2Py ==
 * http://mdp.cti.depaul.edu/examples/static/t2.pdf
 * http://mdp.cti.depaul.edu/examples/static/cookbook.pdf
 * http://mdp.cti.depaul.edu/examples/static/web2py_cheatsheet.pdf
 * https://mdp.cti.depaul.edu/web2py_wiki/default/wiki/tips

This is an MVC environment (like Rails & Django).

=== Model ===
Defines databases in: {{{/models/module.py}}}   (equivalent of {{{inst/mysql-dbcreate.sql}}})

The Models are loaded 1st within Web2Py processing, before the controllers.
So you can import any global modules/set any global variables here.
The Models are imported in alphabetical order, so we load the files which other modules depend on 1st, hence naming them with an underscore: {{{_db.py}}}, {{{_gis.py}}}

=== Controller ===
Python functions in {{{/controllers/module.py}}}

e.g.
{{{
   def list_records():
       list=t2.itemize(table)
       return dict (list=list)
}}}    

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

CSS/Javascript files are stored in {{{/static}}}      (equivalent of {{{www/res}}})


== T2 ==
This plugin is used for [wiki:DeveloperGuidelinesAuthenticationAccess AAA] & simplified [wiki:DeveloperGuidelinesCreateReadUpdateDelete CRUD] (inc Conflict Detection)
 * http://mdp.cti.depaul.edu/examples/static/t2.pdf
We extend the T2 class in {{{modules/sahana.py}}}

=== Conflict Detection ===
Sahana is a multi-user system so there is a potential for multiple users to be editing the same record at once.

Add this field to each table which needs protecting (in {{{models/db.py}}}):
{{{
SQLField('modified_on','datetime'), # Used by T2 to do edit conflict-detection
}}}

This field is also used in [wiki:DeveloperGuidelinesDatabaseSynchronization Database Synchronization]

== Sahana3 Framework ==
These are the bits that we use on top of Web2Py to give the Sahana look & feel:

Populate the side navigation Menus by adding this to each controller:
{{{
module='module'
# Current Module (for sidebar title)
module_name=db(db.module.name==module).select()[0].name_nice
# List Modules (from which to build Menu of Modules)
modules=db(db.module.enabled=='Yes').select(db.module.ALL,orderby=db.module.menu_priority)
# List Options (from which to build Menu for this Module)
options=db(db['%s_menu_option' % module].enabled=='Yes').select(db['%s_menu_option' % module].ALL,orderby=db['%s_menu_option' % module].priority)
}}}

Each function needs to return these values to the view:
  return dict(module_name=module_name,modules=modules,options=options)

List output can be made more functional by this .represent 'widget':
{{{
def shn_list_item(table,resource,action,display='table.name',extra=None):
    if extra:
        items=DIV(TR(TD(A(eval(display),_href=t2.action(resource,[action,table.id]))),TD(eval(extra))))
    else:
        items=DIV(A(eval(display),_href=t2.action(resource,[action,table.id])))
    return DIV(*items)
}}}
You can use it in {{{models/module.py}}} like:
{{{
db.or_organisation.represent=lambda table:shn_list_item(table,resource='organisation',action='display')
db.person.represent=lambda table:shn_list_item(table,resource='person',action='display',display='table.full_name')
db.gis_projection.represent=lambda table:shn_list_item(table,resource='projection',action='display',extra='table.epsg')
}}}

Form labels can be set in a translatable manner using:
   {{{db.table.field.label=T("label")}}}

Form field can be made to use a TEXTAREA by marking the field as being type 'text':
   {{{SQLField('field','text'),}}}

Form field can be made to use a SELECT dropdown by setting the field as a lookup to another table...linked to the 'uuid' field to allow [wiki:DeveloperGuidelinesDatabaseSynchronization Database Synchronization], but displaying a more user-friendly field (such as 'name'):
{{{
SQLField('field',length=64),

db.table.field.requires=IS_NULL_OR(IS_IN_DB(db,'othertable.uuid','othertable.name'))
}}}

Form field being required can be marked using:
   {{{db.table.field.comment=SPAN("*",_class="req")}}}

Help for a form field can be set using:
   {{{A(SPAN("[Help]"),_class="popupLink",_id="tooltip",_title=T("Help Title|This is what this field is for."))}}}

Different Flash styles can be set via:
{{{
session.error=T("Unsupported format!")
redirect(URL(r=request,f=resource))
}}}
or (in a Multiple Table form.accepts):
{{{
response.error=T("Form invalid!")
}}}
Supported styles are:
 * .warning
 * .error
 * .information
 * .confirmation (Standard T2 Flash messages are usually of this sort so we class them in the same way)

=== jQuery Widgets ===
DeveloperGuidelinesDeletableList

=== Options fields ===
Sahana2 has a generic 'field_options' table for storing Options fields.

Sahana3 uses a separate table for each lookup list.


== How to add a new Module? ==
DeveloperGuidelinesNewModule

== Web Services ==
DeveloperGuidelinesWebServices

== GIS ==
[wiki:DeveloperGuidelinesGIS DeveloperGuidelinesGIS]

== Testing ==
DeveloperGuidelinesTesting

== Using Bzr ==
DeveloperGuidelinesBzr

== How to update Web2Py?==
 * Backup the old Web2Py folder
 * Install new Web2Py folder
 * Copy the 'sahana' folder from Backup to Live
 * For some updates, may want to merge updates from
  * {{{/welcome/views/layout.html}}} to {{{/sahana/views/layout_default.html}}}
  * {{{/welcome/static/styles.css}}} to {{{/sahana/static/styles/styles_default.html}}}
  * {{{/static to}}} {{{/sahana/static/styles/media}}}
 * (optional) patches to make admin/dev easier:
  * {{{/applications/admin/web2py_ajax.html}}} : {{{$(document).ready(function() { collapse('static_inner');}}}
  * {{{/welcome/views/default/index.html}}} :
{{{
[ <a href='/sahana'>Sahana</a>
| <a href='/sahana/appadmin/index'>Database</a>
| <a href='/admin/default/design/sahana'>Design</a> 
| <a href='/admin/default/site'>Site</a> ]
}}}

NB T2 is currently updated separately:
 * Download latest T3 (which is where T2 is currently maintained)
 * copy {{{t2.py}}} to {{{/sahana/modules}}}
 * For some updates, may want to merge updates from
  * {{{web2py_ajax.html}}} to {{{/sahana/views/web2py_ajax_t2.html}}}
  * {{{/static}}} to {{{/sahana/static/scripts}}},{{{/sahana/static/styles}}},{{{/sahana/static/styles/media}}}, {{{sahana/static/img/web2py}}}
 


----

=== Translations of this page ===

 * [wiki:DeveloperGuidelinesDE Deutsch]