Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
dev:module_convention [2007/06/14 05:17] chamindra |
dev:module_convention [2010/01/06 20:56] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
The module structure is Sahana is built for flexibility and automation with the least amount of technical configuration details. All you effectively need to do to install a module is untar it in the /mod directory and to remove it just delete the directory. | The module structure is Sahana is built for flexibility and automation with the least amount of technical configuration details. All you effectively need to do to install a module is untar it in the /mod directory and to remove it just delete the directory. | ||
+ | |||
+ | |||
===== Some recommendations before you start a module ===== | ===== Some recommendations before you start a module ===== | ||
Sahana is a disaster managment system, however the Sahana base can be used for other humanitarian-ICT requirements as well. The recommended approach in designing a new module is as follows: | Sahana is a disaster managment system, however the Sahana base can be used for other humanitarian-ICT requirements as well. The recommended approach in designing a new module is as follows: | ||
- | - State you vision for the module in the humanitarian-ICT mailing list and get some initial feedback from the community and some additional contributors to join you preferably | + | |
- | | + | |
+ | * Share your requirements at [[http://groups.yahoo.com/group/humanitarian-ict/|humanitarian-ICT mailing list]] and get some initial feedback and input from the community. The people on this list consist | ||
+ | * Work with the community to define the rest of your module requirements (optional). We recommend the following. | ||
* vision and scope | * vision and scope | ||
* paper prototype of application (i.e. UI screen flows) | * paper prototype of application (i.e. UI screen flows) | ||
* logical schema | * logical schema | ||
* Navigation graph | * Navigation graph | ||
- | | + | |
+ | * The steps below are an initial guide, but it is not complete. Thus it is essential | ||
+ | |||
Line 17: | Line 24: | ||
Here are some conventions that have to be followed for all modules to make them more integrated to the Sahana system and automation that is provided. | Here are some conventions that have to be followed for all modules to make them more integrated to the Sahana system and automation that is provided. | ||
- | * main.inc (required only for sub-application) - This file is the front-controller for the sub-application that you hope to build. Most functionality is directed through this file. This file is not required if the module is a pure admin module. | + | |
- | * conf.inc (required) - Configuration values that a administrator is permitted to change in your module. The configuration values are automatically picked up in the admin section for the administrator to modify and tweak you module. | + | |
- | * admin.inc (optional) - A specific admin function that your module needs to make available to the administrator. Each module can have it's own admin page in the admin panel if this file is included. | + | |
- | + | ||
- | * inst/ | + | |
- | + | ||
- | * inst/ | + | |
+ | * **inst/ | ||
+ | * **inst/ | ||
===== Main Module Skeleton and Convention ===== | ===== Main Module Skeleton and Convention ===== | ||
As mentioned earlier Sahana dynamic plugin architecture is based on certain naming conventions of files and functions. | As mentioned earlier Sahana dynamic plugin architecture is based on certain naming conventions of files and functions. | ||
Line 34: | Line 39: | ||
1. decide on a name unique to it amongst modules, (lets say myapp) | 1. decide on a name unique to it amongst modules, (lets say myapp) | ||
- | 2. create a directory called myapp in the /mod | + | |
+ | 2. make sure your module' | ||
+ | |||
+ | 3. create a directory called myapp in the /mod | ||
mkdir -p mod/myapp | mkdir -p mod/myapp | ||
- | 3. Add the following files as required above | + | 4. Add the following files as required above |
ration variables | ration variables | ||
- | 4. Add the default function for main.inc | + | 5. Add the default function for main.inc |
< | < | ||
Line 100: | Line 108: | ||
default admin function: | default admin function: | ||
- | ===== Conf.inc ===== | + | |
- | The conf.inc file is used for a few purposes. Please do not add you other module specific configurations into this as all conf.inc files included for every HTTP request. The primary use of the conf.inc is to provide a nice name and display order for your module in the main menu. The two variable set for this are $conf[' | + | |
+ | ===== conf.inc ===== | ||
+ | The conf.inc file is used for a few purposes. Please do not add you other module specific configurations into this as all conf.inc files included for every HTTP request. The primary use of the conf.inc is to provide a nice name and display order for your module in the main menu. The two variable set for this are $conf[' | ||
Typical usage is as follows | Typical usage is as follows | ||
Line 136: | Line 146: | ||
</ | </ | ||
- | ==== Checking | + | |
+ | ===== Module Dependencies ===== | ||
+ | |||
+ | ==== Checking | ||
Now that Sahana modules have become far more integrated, it is important for us to check if modules we are depending on exist before we present a feature in our module. E.g. Inventory management' | Now that Sahana modules have become far more integrated, it is important for us to check if modules we are depending on exist before we present a feature in our module. E.g. Inventory management' | ||
Line 147: | Line 161: | ||
the function lives in / | the function lives in / | ||
+ | ==== Module Database Dependencies ==== | ||
+ | As Sahana becomes more integrated you may find yourself referencing and even creating data in tables belonging to other modules. For example adding an item in your module to the gis. Remember that it is your responsibility to clean up after yourself. So remember to use the aproprate **Create Modify** and **Delete** interfaces in other modules so as not to leave residual/ |