DeveloperGuidelines

== How to add a new module? ==

The Eden Book has a tutorial for [http://en.flossmanuals.net/sahana-eden/building-a-new-application adding a new module]. However, it is simplified from the normal way modules are included in Eden. Especially, the model file differs.


=== Model ===

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

'''Note''' 
 * Add your module to settings.modules in {{{private/templates/<template>/config.py}}} if it is for a specific template.
 * Add it to {{{private/templates/default/config.py}}} to provide an example of how your module should be entered in settings.modules.
 * Add an import statement to {{{models/00_tables.py}}}

Add tables to modules/s3db/<MODULE NAME>.py file, as-required for your resources.
To avoid namespace clashes, use your module name as a prefix for table names.
Follow with underscore and the name of the resource your table represents: module_resource. Resource names should be unique.

E.g. if building a Vehicle Management System, create s3db.vms_vehicle:
{{{
module = "vms"
resource = "vehicle"

tablename = "%s_%s" % (module, resource)
table = s3db.define_table(tablename,
                Field("name"),
                *s3_meta_fields())
table.uuid.requires = IS_NOT_IN_DB(db, "%s.uuid" % table)
table.name.requires = IS_NOT_EMPTY()
table.name.comment = SPAN("*", _class="req")
}}}

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

Add CRUD functions for your tables:
{{{
module = request.controller

def vehicle():
    "RESTful CRUD controller"
    resource = request.function
    return s3_rest_controller(module, resource)
}}}

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

Add the messages for your resources:
{{{
def vehicle():
    "RESTful CRUD controller"
    resource = request.function
    s3.crud_strings[tablename] = 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"))

    return s3_rest_controller(module, resource)
}}}

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

=== 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