= Developer Guidelines - Basics = 
[[TOC]]
Here are some helpful hints to get started developing in Sahana Eden.

* [wiki:DeveloperGuidelines/Sahana2Migration Help for Developers Migrating from Sahana PHP]
* [wiki:DeveloperGuidelines/DjangoMigration Help for Developers Migrating from Django]

== Running Sahana Eden ==
{{{
cd .. # the web2py main directory
python web2py.py
}}}
Or if you don't want to have to enter a password (or have issues launching the Web2Py GUI).
{{{
python web2py.py -a 1234
}}}

== Wiping the Database ==
Out of the box Sahana Eden is set to use the SQLite database. If you want to wipe all the data, simply delete the {{{databases/}}} directory, along with the {{{sessions/}}} directory (this contains details about your login - which will be invalid as you'll be deleting the user account). The next time you run Sahana Eden, it will recreate the database tables.

== Pre-Populating Data ==
Sahana Eden is able to "[DeveloperGuidelines/PrePopulate Pre-Populate]" data so you can explore/test/develop the application with different types of data. Pre-Populate options are associated with the [DeveloperGuidelines/Templates Templates], but they can be set in {{{models/000_config.py}}}.

{{{IFRC_Train}}} is a good set of pre-populate to use (See: https://github.com/flavour/eden/tree/master/modules/templates/IFRC_Train). It also has an admin user account: !admin@example.com password: testing. To use it edit {{{models/000_config.py}}}:

After:
{{{
# =============================================================================
# Over-rides to the Template may be done here
}}}
Add (or un-comment):
{{{
settings.base.prepopulate += ("IFRC", "IFRC/Train")
}}}

Pre-populate data will only be created if the database is empty, so you may need to wipe the database first. It may take a few minutes to load the data.

== Debug Mode ==
In {{{models/000_config.py}}} uncomment this line:
{{{
settings.base.debug = True
}}}
to:
* Use the non-minified CSS & JS
* See changes in {{{modules/s3db}}} files without restarting Web2Py

== Running a Sahana Eden Python Shell ==
To open a Python Shell in the Sahana Eden Environment, where you can inspect Web2Py and Sahana Eden variables as well as access the data:
{{{
cd web2py
python web2py.py -S eden -M
}}}
To have database changes be persistent (e.g. to see via Web UI), you will need to commit the transactions: {{{db.commit()}}}.

== Python ==
Indentation matters (use 4 spaces instead of Tabs)
* http://diveintopython.net
* http://openbookproject.net/thinkcs/python/english2e/
* http://software-carpentry.org
* Python v2 documentation: http://docs.python.org/ (We are currently using v2.7.)

== 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 tutorial 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.

Can execute a controller to be able to access its functions using:
{{{
execfile("applications/eden/controllers/mycontroller.py", globals())
}}}

Web2Py can be extended through [http://www.web2py.com/plugins Plugins] & also has a [http://web2pyslices.com recipes site].

* [http://web2py.com/book Web2py Book]

== Javascript ==
 * Basic Javascript tutorials
  * https://developer.mozilla.org/en/learn/javascript
  * http://www.w3schools.com/js/
   * Although see http://w3fools.com on why you may wish to avoid them

 * 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://www.sencha.com
  * http://dev.sencha.com/deploy/ext-4.0.0/examples/
  * 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/

Private variables should be protected, e.g. using the Module Pattern:
 * http://yuiblog.com/blog/2007/06/12/module-pattern/
 * http://www.adequatelygood.com/2010/3/JavaScript-Module-Pattern-In-Depth

Can test out the performance of different options to achieve a task using:
 * http://jsperf.com

Can check quality using JSLint:
 * http://www.javascriptlint.com/online_lint.php
== XSLT ==
To transform XML (and CSV) files for importing and exporting data.
* [wiki:XsltTemplates Sahana Eden XSLT Documentation]
* XPath: http://www.w3schools.com/xpath/default.asp
* XSLT: http://www.w3schools.com/xsl/default.asp
* [http://codespeak.net/lxml/tutorial.html lxml Tutorial]

== Debugging ==
=== Python ===
* Use the [DeveloperGuidelines/Eclipse Eclipse IDE] to be able to set breakpoints and inspect expressions.
* WSGI likes print statements to go to {{{sys.stderr}}} not {{{sys.stdout}}}: http://code.google.com/p/modwsgi/wiki/DebuggingTechniques
* use Web2Py shell: http://www.vimeo.com/879939
* use [http://ipython.scipy.org/moin/ IPython] for interactive exploration (on Windows, install [http://ipython.scipy.org/moin/PyReadline/Intro PyReadline])
* use [http://groups.google.com/group/web2py/browse_thread/thread/cc13960a5079b2d5# FirePy] to see logging output to Console (to view with Firebug)
* Log to a File: http://groups.google.com/group/web2py/browse_thread/thread/e20d0bd2e542aa14
* Debug Tools: http://docs.python.org/library/debug.html
* Use [http://stackoverflow.com/questions/2654113/python-how-to-get-the-callers-method-name-in-the-called-method Inspect] to check which function called the one you're troubleshooting:
{{{
import inspect
curframe = inspect.currentframe()
calframe = inspect.getouterframes(curframe, 2)
current.log.debug("caller name: %s" % calframe[1][3])
}}}
 * Debug SQL Queries:
{{{
vi gluon/dal.py
class BaseAdapter()
    def select():
        def response(sql):
            if "searchphrase" in sql:
                current.log.debug("Query: %s" % query)
                current.log.debug("SQL: %s" % sql)
}}}
 * Debug Views:
{{{
vi gluon/globals.py
    def write(self, data, escape=True):
        try:
            ...All Old Code ...
        except Exception, error:
            # Put Eclipse breakpoint on the below line
            exc_type, exc_value, exc_traceback = sys.exc_info()
            pass
}}}
* [http://aymanh.com/python-debugging-techniques Python Debugging Techniques]
 * Insert these statements into your code
  * Get a Python shell up to explore interactively: {{{import code; code.interact(locals=locals()}}}
  * Get a full stack trace: {{{import pdb; pdb.set_trace()}}}
* winpdb: http://groups.google.com/group/web2py/msg/ee46125b7c93fdd4
* WingIDE: http://www.wingware.com/
 * Using with Web2Py: http://www.wingware.com/doc/howtos/web2py
* [DeveloperGuidelines/Eclipse Eclipse] IDE
* Unicode:
 * "Decode early, Unicode everywhere, Encode late": http://farmdev.com/talks/unicode/
 * http://boodebr.org/main/python/all-about-python-and-unicode
* Python Design Patterns:
 * http://www.youtube.com/watch?v=Er5K_nR5lDQ
 * http://videolectures.net/youtube_martelli_python/

=== HTML, CSS, and Javascript ===

Each of the major browsers has tools available for viewing HTML page structure and form data, Javascript code, CSS.  Some also support Javascript debugging, including setting breakpoints and viewing values in variables.

* Firefox: Install the [https://addons.mozilla.org/en-US/firefox/addon/firebug/ Firebug] plugin.  Start Firebug by clicking the bug icon in the upper right.  After the tools open in the lower half of the page, load the page you want to debug.

* Chrome: Open the [https://developers.google.com/chrome-developer-tools/ Chrome developer tools] with Chrome menu (three bar icon) -> Tools -> Developer tools.

* Internet Explorer: Open the [http://msdn.microsoft.com/library/ie/bg182326%28v=vs.85%29 IE developer tools] with F12, or Tools (gear icon) -> F12 Developer Tools.  Note that you can test behavior of pages under earlier versions of IE by setting your current IE to behave as earlier versions.  In the developer tools menu bar, click Browser Mode and select the desired version.

Other tools that may be of interest:

* use [http://www.sprymedia.co.uk/article/Visual+Event Visual Event] to see which events are active.
* use Venkman: http://www.mozilla.org/projects/venkman/
* use Fiddler for compressed files: http://www.yuiblog.com/blog/2008/06/27/fiddler
* http://pastebin.me (allows edits of HTML & previews)
* http://jsfiddle.net (allows edits of JS & previews)
* http://yura.thinkweb2.com/domlint/
 * http://www.jslint.com/lint.html
* IE6 cheatsheet: http://www.virtuosimedia.com/tutorials/ultimate-ie6-cheatsheet-how-to-fix-25-internet-explorer-6-bugs

== Additional Tips ==
''See:'' DeveloperGuidelines/Tips