You are here: start » dev » module_convention

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
dev:module_convention [2007/06/14 05:12]
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 + 
-  - Create a simple requirement specification similar to what was done for [[http://www.reliefsource.org/foss/images/6/69/Dvr_v1.0.pdf | People Registry]] or [[http://www.reliefsource.org/foss/images/0/00/Orgregv2.0.pdf | Organization Registry ]]. As Part of the design we recommend the following as a minimum+  * Document your requirements and specification for your module in the Sahana "Module Ideas" Forum [[http://forum.sahana.lk/viewforum.php?f=9|here]].  
 +  * 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 of emergency management practitioners, humanitarian workers and academics and they can help you refine your requirements a great deal.  
 +  * 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 
-  - Place it on the Reliefsource wiki under [[http://www.reliefsource.org/foss/index.php/Sahana | modules ]] and send it for feedback to the humanitarian-ICT mailing list+  * The next stage is start developing the module or get some people to work with you to build the module. You should now share this with the [[https://lists.sourceforge.net/lists/listinfo/sahana-maindev |sahana-maindev]] list where all the sahana developers are registered.  
 +  * The steps below are an initial guide, but it is not complete. Thus it is essential for you to collaborate on the sahana-maindev list in building your module. 
 + 
  
  
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.+  * **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.+  * **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. +  * **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/dbcreate.sql (required) - The MySQL database creation script for module installation. This is automatically used by the web installer or the package installer. +
- +
-  * inst/setup.inc (required) - A setup script beyond the MySQL database creation for module installation. This is automatically used by the web installer or the package installer. The basic version will have the package version and details, whist the advanced form of this script will have installation, upgrade and uninstallation functions+
  
 +  * **inst/dbcreate.sql** (required) - The MySQL database creation script for module installation. This is automatically used by the web installer or the package installer.
  
 +  * **inst/setup.inc** (optional) - A setup script beyond the MySQL database creation for module installation. This is automatically used by the web installer or the package installer. The basic version will have the package version and details, whist the advanced form of this script will have installation, upgrade and uninstallation functions
 ===== 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's name conforms to these requirements: http://wiki.sahana.lk/doku.php/dev:php_coding_convention#choosing_a_name_for_a_module_in_sahana_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
  
 <code> <code>
Line 100: Line 108:
   default admin function:    shn_or_adm_default()   default admin function:    shn_or_adm_default()
  
-===== 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['mod_'.<mod>.'_name'] and $conf['mod_'.<mod>.'_menuorder'], wheer <mod> is the directory of your module.+ 
 +===== 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['mod_'.<mod>.'_name'] and $conf['mod_'.<mod>.'_menuorder'], where <mod> is the directory of your module.
  
 Typical usage is as follows Typical usage is as follows
Line 117: Line 127:
 This is the name displayed in the menu. If no nice name is provided you modules base directory name is used This is the name displayed in the menu. If no nice name is provided you modules base directory name is used
  
-===== Checking module dependencies =====+ 
 +===== inst/setup.inc ===== 
 + 
 +The inst/setup.inc will have some meta-data at the head specifying the classification of the package, as well as installation, upgrade and uninstallation functions. 
 + 
 +<code> 
 + 
 +$package['mod_mpr_version'] = '0.4'; 
 +$package['mod_vm_depends'] = array( 'mpr/0.2', 'or', 'gis/0.3-0.4'); 
 +$package['mod_vm_conflicts'] = array ( 'vol', 'dvr/0.3-0.5'); 
 + 
 +function shn_vm_install() {.. 
 + 
 +function shn_vm_upgrade() {.. 
 + 
 +function shn_vm_uninstall() { .. 
 + 
 +</code> 
 + 
 + 
 +===== Module Dependencies ===== 
 + 
 +==== Checking Module Dependencies ==== 
 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's dependency on the catalog system or providing a link to add camp in the camp registry from the situation mapping module only if the module 'cr' exists. 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's dependency on the catalog system or providing a link to add camp in the camp registry from the situation mapping module only if the module 'cr' exists.
  
Line 128: Line 161:
 the function lives in /inc/lib_modules.inc so it has to be included before you call it. the function lives in /inc/lib_modules.inc so it has to be included before you call it.
  
 +==== 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/incorect references lying around in the system.

Trace:

Navigation
QR Code
QR Code dev:module_convention (generated for current page)