Changes between Version 43 and Version 44 of DeveloperGuidelinesS3Framework


Ignore:
Timestamp:
08/31/10 19:13:13 (11 years ago)
Author:
Fran Boon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelinesS3Framework

    v43 v44  
    1 == Sahana Eden Framework ==
     1[[TOC]]
     2= Sahana Eden Framework =
    23We have built an S3 framework as a higher level of abstraction on top of Web2Py.[[BR]]
    34This should be used by modules where possible, but if more power is needed then drop down a level of two (to T2, to base Web2Py or to raw Python).
     
    1718This provides details on how to configure your Model & Controllers. Views may not be required, other than index.html
    1819
    19 ==== Custom Functions Plugged into REST ====
     20=== Custom Functions Plugged into REST ===
    2021In many cases it may be much easier to implement non-CRUD resource functions as REST-plugins instead of separate controllers.
    2122 * see search_simple for an example
     
    3435and finally, XRequest remembers the record ID until the next request to the same resource in the same session, which can be helpful when producing links (especially _next's) not knowing the record ID.
    3536
    36 === Mandatory ===
    37 Each Controller should start like this (to populate the side navigation Menus):
     37== Mandatory ==
     38Each Controller should start like this:
    3839{{{
    39 module = 'module'
    40 # Current Module (for sidebar title)
    41 module_name = db(db.module.name==module).select()[0].name_nice
     40module = "module"
    4241# Options Menu (available in all Functions' Views)
    4342response.menu_options = [
    44     [T('Home'), False, URL(r=request, f='index')],
    45     [T('Add Person'), False, URL(r=request, f='person', args='create')],
    46     [T('List People'), False, URL(r=request, f='person')],
    47     [T('Search People'), False, URL(r=request, f='person', args='search')]
     43    [T("Home"), False, URL(r=request, f="index")], [
     44        [T("Resources"), False, URL(r=request, f="resource")],
     45        [T("List"), False, URL(r=request, f="person")],
     46        [T("Add"), False, URL(r=request, f="resource", args="create")],
     47        [T("Search People"), False, URL(r=request, f="resource", args="search")]
     48    ]]
    4849]
    4950}}}
    5051
    51 Each function needs to return this value to the view:
    52   return dict(module_name=module_name)
    53 
    5452All tables which are user-editable need to be protected for conflict resolution & synchronization using the predefined reusable fields {{{timestamp}}} & {{{uuidstamp}}}.[[BR]]
    55 These are defined in {{{models/00_db.py}}}:
     53These are defined in {{{models/00_tables.py}}}:
    5654{{{
    5755# Reusable timestamp fields
    58 timestamp = SQLTable(None,'timestamp',
    59             db.Field('created_on','datetime',
     56timestamp = SQLTable(None, "timestamp",
     57            Field("created_on", "datetime",
    6058                          writable=False,
    6159                          default=request.now),
    62             db.Field('modified_on','datetime',
     60            Field("modified_on", "datetime",
    6361                          writable=False,
    6462                          default=request.now,update=request.now))
    6563
    6664# We need UUIDs as part of database synchronization
    67 import uuid
    68 uuidstamp = SQLTable(None,'uuidstamp',
    69             db.Field('uuid',length=64,
     65 import uuid
     66uuidstamp = SQLTable(None, "uuidstamp",
     67            Field("uuid", length=64,
    7068                          writable=False,
    7169                          default=uuid.uuid4()))
    7270}}}
    7371
    74 === Optional ===
     72== Optional ==
    7573Other reusable fields are available to add Foreign Key links to key tables, such as 'location_id' to add a GIS location for Mapping, 'person_id' to add a Person & 'organisation_id' to add a link to an Organisation.
    7674
    7775List output are made more functional by this .represent 'widget':
    7876{{{
    79 def shn_list_item(table, resource, action, display='table.name', extra=None):
     77def shn_list_item(table, resource, action, display="table.name", extra=None):
    8078    if extra:
    8179        items = DIV(TR(TD(A(eval(display), _href=t2.action(resource, [action, table.id]))), TD(eval(extra))))
     
    8684This is called in {{{models/01_crud.py}}} in the REST Controller:
    8785{{{
    88 db.pr_person.represent = lambda table:shn_list_item(table, resource='person', action='display', display='table.full_name')
     86db.pr_person.represent = lambda table:shn_list_item(table, resource="person", action="display", display="table.full_name")
    8987}}}
    9088
     
    9391
    9492Form field can be made to use a TEXTAREA by marking the field as being type 'text':
    95    {{{Field('field', 'text'),}}}
     93   {{{Field("field", "text"),}}}
    9694
    9795Form field can be made to use a SELECT dropdown by setting the field as a lookup to another table...linked to the 'id' field to allow [wiki:DeveloperGuidelinesDatabaseSynchronization Database Synchronization], but displaying a more user-friendly field (such as 'name'):
    9896{{{
    99 Field('field', db.othertable),
     97Field("field", db.othertable),
    10098
    101 db.table.field.requires = IS_NULL_OR(IS_IN_DB(db, 'othertable.id', 'othertable.name'))
     99db.table.field.requires = IS_NULL_OR(IS_ONE_OF(db, "othertable.id", "othertable.name"))
    102100}}}
    103101
     
    127125 * .confirmation (Default response.flash is styled like this)
    128126
     127==== Global variables ====
     128Use session for persistent variables
     129
     130Use response for one-off variables which are visible in views without explicit passing
     131
    129132=== Settings ===
    130 System-wide settings have their default values set in {{{models/00_db.py}}}'s {{{s3_settings}}} table.
     133System-wide settings have their default values set in {{{models/000_config.py}}}.
     134
     135A few settings are still in the s3_settings table.
    131136
    132137Upon 1st run of the system, these settings are loaded into the database from where they can subsequently be edited to configure the running instance.
     
    156161=== Conflict Detection ===
    157162Sahana is a multi-user system so there is a potential for multiple users to be editing the same record at once.[[BR]]
    158 We use T2 to handle this for us.
     163We use Web2Py's CRUD to handle this for us.
    159164
    160165Add this reusable field to each table which needs protecting (in {{{models/module.py}}}):