Changes between Initial Version and Version 1 of DeveloperGuidelinesS3Framework

Timestamp:

01/09/09 18:49:55 (16 years ago)

Author:

Fran Boon

Comment:

--

DeveloperGuidelinesS3Framework

@@ +1 @@
+== SahanaPy Framework ==
+We have built an S3 framework as a higher level of abstraction on top of T2.[[BR]]
+This 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).
+
+T2 is used for:
+ * [wiki:DeveloperGuidelinesAuthenticationAccess AAA]
+ * simplified [wiki:DeveloperGuidelinesCreateReadUpdateDelete CRUD]
+ * Conflict Detection
+We extend the T2 class in {{{modules/sahana.py}}}.[[BR]]
+Patches to the framework should be done here.[[BR]]
+If they're generic enough then they can be suggested to Massimo for moving upstream to either Web2Py or T2.
+
+We extend the CRUD with a [wiki:BluePrintRESTImplementation RESTlike controller].[[BR]]
+This provides details on how to configure your Model & Controllers. Views may not be required, other than index.html
+
+=== Mandatory ===
+Each Controller should start like this (to populate the side navigation Menus):
+{{{
+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)
+
+=== Optional ===
+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)
+
+=== Settings ===
+System-wide settings have their default values set in {{{models/_db.py}}}'s {{{shn_default}}}.
+
+Upon 1st run of the system, these settings are pulled into the default_setting table in the database from where they can susequently be edited to configure the running instance.
+
+If these settings are required by all Views then can patch the session to see them in {{{models/_db.py}}}'s {{{shn_sessions()}}}.[[BR]]
+e.g. response.debug is made available to the default {{{layout.html}}} this way.
+
+If you wish to clean out all settings to import afresh, then close down Web2Py & start up in shell mode:
+{{{
+python web2py.py -S sahana -M
+}}}
+Then run:
+{{{
+shn_db_clean(db)
+}}}
+(This function is configured in {{{modules/sahana.py}}})
+
+
+Modules can set up their own configuration settings tables in a similar way (e.g. GIS does this)
+
+=== jQuery Widgets ===
+ * [wiki:DeveloperGuidelinesDeletableList Deletable List]
+
+=== Conflict Detection ===
+Sahana is a multi-user system so there is a potential for multiple users to be editing the same record at once.[[BR]]
+We use T2 to handle this for us.
+
+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]
+
+----
+DeveloperGuidelines