Developer Guide

Install a Development Environment

• see InstallationGuidelinesDeveloper

Python

Indentation matters (use 4 spaces instead of Tabs)

• ​http://diveintopython.org
• ​http://openbookproject.net/thinkcs/python/english2e/
• ​http://software-carpentry.org
• 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 ​MVC environment (like ​Rails & ​Django. ​Django polls tutorial conversion course).

Web2Py can work at several different levels of abstraction.
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.

• ​http://web2py.com/examples/default/docs (recommend the 'New Cookbook' as well as the ​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 ​Plugins & also has a ​recipes site.

Tutorial

This tutorial was given at SahanaCamp 1.1 in Taiwan:

• ​http://www.slideshare.net/AidIQ/sahana-introduction-to-the-code-v2
• DeveloperQuickstart

Model

Defines databases in: /models/module.py

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 appropriately:
000_config.py, 01_crud.py, 02_pr.py, 03_gis.py, etc

Controller

Python functions in /controllers/module.py
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

Developer Guidelines

• Sahana Eden Framework: S3
  • S3ReusableField
  • REST Controller
    • URL Format
  • S3XRC

• Help for Developers Migrating from Sahana PHP
• Help for Developers Migrating from Django
• How to add a new Module?
• Using Bzr Version Control
  • How to get your work Merged into Trunk

• Code Conventions

• CSS
  • Themes
• GIS - Mapping
• SVG - Charts
• Internationalization
• Architecture
• Documentation

• Usability
• Optimisation

• Testing
  • TestCases - User Testing - List of things to test

• Release Process
  • Data Migration

• StableCore

• Tips - useful links to explore

TranslatedPages

Mobile

• Android - Developer Guidelines for the Android client

Understanding the Domain

• International Development NGOs
• US Emergency Response: FEMA Incident Command System - free online training (exam only available for US citizens)
  • ​ICS 100 - Introduction to ICS (Incident Command System)
  • ​ICS 700 - Introduction to NIMS (National Incident Management System)
  • ​ICS 800 - Introduction to NRF (National Response Framework)
  • ​ICS 101 - Deployment Basics (individual preparation)
  • ​ICS 701 - NIMS Multiagency Coordination System
  • ​ICS 702 - NIMS Public Information Systems
  • ​ICS 703 - NIMS Resource Management
  • ​ICS 704 - NIMS Communications and Information Management
  • ​ICS 200 - Single Resources and Initial Action Incidents (for supervisors)