Version 150 (modified by 14 years ago) ( diff ) | ,
---|
Table of Contents
Developer Guide
Developer Guidelines
Development Enviroment
- How to install a Development Enviroment
- Using Bzr Version Control
Framework
Functionality
User Interface
Quality
Release Process
Other Resources
- Tips - useful links to explore
Mobile
- 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 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:
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 fromviews/*_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:
- 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:
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: