DeveloperGuidelines

How to add a new module?

Summary:

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

Model

Add your module to models/000_config.py

This makes it visible on the front page & the menu.

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.vts_vehicle:

module = "vts"
resource = "vehicle"

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")

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 shn_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 shn_rest_controller(module, resource)

Add a menu:

# 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")]
]

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