wiki:DeveloperGuidelinesNewModule

Version 15 (modified by Fran Boon, 13 years ago) ( diff )

single/plural bad for Internationalisation!

DeveloperGuidelines

How to add a new module?

Copy an existing module, paste & edit. Good modules to look at to start with are or & cr as these are simplest & standard.

Model

Add module to db.module:

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

Create a file /models/module.py

This needs a table to store the module's menu options in:

module='name'

# Menu Options
db.define_table('%s_menu_option' % module,
                SQLField('name'),
                SQLField('function'),
                SQLField('description',length=256),
                SQLField('priority','integer'),
                SQLField('enabled','boolean',default='True'))
db['%s_menu_option' % module].name.requires=[IS_NOT_EMPTY(),IS_NOT_IN_DB(db,'%s_menu_option.name' % module)]
db['%s_menu_option' % module].name.requires=IS_NOT_EMPTY()
db['%s_menu_option' % module].priority.requires=[IS_NOT_EMPTY(),IS_NOT_IN_DB(db,'%s_menu_option.priority' % module)]

Add additional 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,
                SQLField('modified_on','datetime',default=now),
                SQLField('uuid',length=64,default=uuid.uuid4()),
                SQLField('name'))
db['%s' % table].represent=lambda table:shn_list_item(table,resource='vehicle',action='display')
db.veh_vehicle.name.requires=IS_NOT_EMPTY()
db.veh_vehicle.name.comment=SPAN("*",_class="req")

Also 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')
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')
exec('crud_strings.%s=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)' % resource)

Controller

Add CRUD functions for these tables to /controllers/module.py:

def vehicle():
    "RESTful CRUD controller"
    return shn_rest_controller(module,'vehicle')

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

Populate the module's menu_options table with the functions that you wish to expose to the module's front page & left-hand navigation bar.

Views

Add HTML templates for any custom functions: /views/module/function.html

NB Only index.html is required to start with since the RESTful controller re-uses standard views

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.