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:
 * http://127.0.0.1:8000/sahana/appadmin/select/db?query=db.module.id%3E0

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.

To avoid namespace clashes, use the format: {{{db.module_table}}}

Add a section for messages for your resources to {{{models/_db.py}}}:
{{{
def shn_crud_strings_lookup(resource):
    "Look up CRUD strings for a given resource."
    elif resource=='shelter':
        return Storage(title_create=T('Add Shelter'),
            title_display=T('Organisation Details'),
            title_list=T('List Shelters'),
            title_update=T('Edit Shelter'),
            subtitle_list=T('Shelters'),
            subtitle_create=T('Add New Shelter'),
            label_list_button=T('List Shelters'),
            label_create_button=T('Add Shelter'),
            msg_record_created=T('Shelter added'),
            msg_record_modified=T('Shelter updated'),
            msg_record_deleted=T('Shelter deleted'),
            msg_list_empty=T('No Shelters currently registered'))
}}}

Copy/paste & do just a few small tweaks once pasted:
 * Search/Replace 'Organisation' with Your_resource
 * Fix plurals, if required (e.g. Persons -> People, Classs to Classes, Metadatas -> Metadata)

=== Controller ===
Add CRUD functions for these tables to {{{/controllers/module.py}}}:
{{{
def shelter():
    "RESTful CRUD controller"
    return shn_rest_controller(module,'shelter')
}}}

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