DeveloperGuidelines

== How to add a new module? ==
Summary:
 * Copy an existing module, paste & edit.
 * You will need to delete the database in order to load the new model (del ...\sahana\databases\*.*.)
 * Good modules to look at to start with are or & cr as these are simplest & standard.

=== Model ===
Add module to db.s3_module:
 * http://127.0.0.1:8000/sahana/appadmin/select/db?query=db.s3_module.id%3E0

This makes it visible on the front page & the left-hand navigation menu.

To make this change in code not just in this instance, then edit {{{/models/01_modules.py}}}:
{{{
# Populate table with Default modules
if not len(db().select(table.ALL)):
    table.insert(
        name="veh",
        name_nice="Vehicle Management System",
        priority=<INSERT NEXT SEQUENTIAL PRIORITY HERE>,
        description="Allows the management of vehicles",
        enabled="True"
	)
}}}

You will need to delete the database in order to load the new model (del ...\sahana\databases\*.*.)

Create a file {{{/models/<MODULE NAME>.py}}}

Add tables to this file, as-required for your resources.[[BR]]
To avoid namespace clashes, use the format: {{{db.module_table}}}

e.g. if building a Vehicle Management System, create db.veh_vehicle:
{{{
module = 'veh'
resource = 'vehicle'

# Current Module (for sidebar title)
module_name = db(db.s3_module.name==module).select().first().name_nice

tablename = module + '_' + resource
table = db.define_table(tablename, timestamp, uuidstamp,
                Field('name'))
table.uuid.requires = IS_NOT_IN_DB(db, '%s.uuid' % table)
table.name.requires = IS_NOT_EMPTY()
table.name.comment = SPAN("*", _class="req")
}}}

Add the messages for your resources:
{{{
s3.crud_strings[table] = Storage(
    title_create = T('Add Vehicle')
    title_display = T('Vehicle Details')
    title_list = T('List Vehicles')
    title_update = T('Edit Vehicle')
    title_search = T('Search Vehicles')
    subtitle_create = T('Add New Vehicle')
    subtitle_list = T('Vehicles')
    label_list_button = T('List Vehicles')
    label_create_button = T('Add Vehicle')
    label_delete_button = T('Delete Vehicle')
    msg_record_created = T('Vehicle added')
    msg_record_modified = T('Vehicle updated')
    msg_record_deleted = T('Vehicle deleted')
    msg_list_empty = T('No Vehicles currently registered'))
}}}

=== Controller ===
Create a file: {{{/controllers/<MODULE NAME>.py}}}

Add the S3 framework functions:
{{{
module = 'veh'
# Current Module (for sidebar title)
module_name = db(db.s3_module.name==module).select().first().name_nice

# Options Menu (available in all Functions' Views)
response.menu_options = [
    [T("Home"), False, URL(r=request, f="index")],
    [T("Add Vehicle"), False, URL(r=request, f="vehicle", args="create")],
    [T("List Vehicles"), False, URL(r=request, f="vehicle")],
    [T("Search Vehicles"), False, URL(r=request, f="vehicle", args="search")]
]

}}}

Add CRUD functions for your tables:
{{{
def vehicle():
    "RESTful CRUD controller"
    return shn_rest_controller(module, "vehicle")
}}}

Manual method for if/when you need more control: DeveloperGuidelinesCreateReadUpdateDelete

=== Views ===
Add HTML templates for any custom functions: {{{/views/<MODULE NAME>/<FUNCTION NAME>.html}}}

NB Only {{{index.html}}} is required to start with since the RESTful controller normally re-uses standard views.[[BR]]
If Custom Views are wanted they are detected automatically if files are found in {{{/views/<MODULE NAME>/<RESOURCE>_<METHOD>.html}}}

DeveloperGuidelines
DeveloperGuidelines