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_module.py:

# Populate table with Default modules
if not len(db().select(db[table].ALL)):
    db[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.
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'
table = module + '_' + resource
db.define_table(table, timestamp, uuidstamp,
                db.Field('name'))
db[table].uuid.requires = IS_NOT_IN_DB(db, '%s.uuid' % table)
db.veh_vehicle.name.requires = IS_NOT_EMPTY()
db.veh_vehicle.name.comment = SPAN("*", _class="req")

Add the messages for your resources:

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')
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')
crud_strings[table] = Storage(title_create=title_create, title_display=title_display, title_list=title_list, title_update=title_update, subtitle_create=subtitle_create, subtitle_list=subtitle_list, label_list_button=label_list_button, label_create_button=label_create_button, msg_record_created=msg_record_created, msg_record_modified=msg_record_modified, msg_record_deleted=msg_record_deleted, msg_list_empty=msg_list_empty)

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()[0].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.
If Custom Views are wanted they are detected automatically if files are found in /views/<MODULE NAME>/<RESOURCE>_<METHOD>.html

DeveloperGuidelines DeveloperGuidelines