Modules


The goal of the module system is to allow other developers to write and integrate code into OpenMRS without having to modify the core codebase. Our online Module Repository has been developed to facilitate searching and sharing of modules.

[edit]

What is a module?

  • Modules are packaged java code that can be installed into a running OpenMRS instance and is able to modify almost all aspects of OpenMRS. They can provide web pages, add tables, change how service calls work, and add new functionality (like report options, person attribute types, etc)
[edit]

Quick Overview

  • Modules can modify with the service layer methods via Aspect Oriented Programming (AOP). All core services and all module services are able to be wrapped and manipulated.
  • If in a web context, modules can add their own jsp web pages in their /web/module folder. They link these pages to controllers and to OpenMRS via the Spring context /metadata/moduleApplicationContext.xml
  • Modules can add to and current jsp page in the web layer via extension points. A module registers an extension in the /metadata/config.xml for each extension point in the system to which it wants to add content.
  • Modules are able add and modify tables in the database. The sqldiff.xml file in the metadata folder holds the diffs.
  • The file extension for modules is ".omod". However, a Module is simply a jar underneath. This different extension was chosen for two reasons: First, its just a short form of "OpenMRS Module". Second, its a unique extension and there aren't any other programs known to be using it.
  • Find other modules and examples in the OpenMRS Module Repository. Add your own using your Trac login and password.
[edit]

Overall Module Structure

build
Folder automatically created by build script
Contains the compiled files and pre-jarring files
dist
Folder automatically created by build script
Contains the distributable .omod (openmrs module) file
lib
Place any module specific libraries in this folder. All jars in this folder will be packaged into your distributed omod file.
lib-common
Place the jars/libraries that you need for building/compiling/testing your module. The jars in this folder will not be included in the packaged module.
metadata
config.xml
*.hbm.xml files
messages_*.properties files
moduleApplicationContext.xml
sqldiff.xml
src
Contains the java source files for the module
web
module
Contains the jsp and web files. All files will be places into /WEB-INF/modules/moduleId/*
portlets
Any portlet in this folder can be accessed like any other portlet (i.e. <openmrs:portlet id="thismodulesportlet" moduleId="moduleId" />)
resources
All non-jsp files need to be placed and accessed in this folder
src
Contains web java source files like controllers and servlets
build.xml
Shouldn't need modifying other then the Module Name (for display) and Module version
Copies the right files into their necessary places and creates the omod file


[edit]

FAQ

How do I create a new module?
See Creating Your First OpenMRS Module
Where can I find examples?
Several samples have been committed to the subversion repository: http://dev.openmrs.org/browser/openmrs-modules . All code in the repository is open for download
How do I deploy my module?
  1. Run the the target "package-module" in the ant build.xml in the root of your module.
  2. Option 1: Go to Manage Modules in the Administration section of the webapp. Upload your compiled .omod file from the /dist folder in your module
  3. Option 2: Drop your .omod file into the <openmrs application directory>/modules folder and restart openmrs. (The application directory is either /home/tomcatuser/.OpenMRS or c:/docs and settings/tomcatuser/application data/openmrs)
How do I redeploy my updated module?
Option 1: Choose the "undeploy" link on the Manage Modules page and then deploy your module again
Option 2: Drop your new .omod file in the application data directory and restart openmrs
How do I specify Module Updates?
There is a page dedicated to the update.rdf file
How can I allow administration of the modules through the web?
You need to be sure the line module.allow_web_admin=true is in your runtime properties file
Can I store my module source code in your subversion repository?
We welcome and encourage you to use our source code repository. Contact code@openmrs.org for additional help.
How do I perform unit testing in my module?
See Module Unit Testing
How can my module access the database? (Aka How can my module create its own service?)
See page on creating the moduleApplicationContext.xml file
How do I extend an OpenMRS table with a module?
See Extending an OpenMRS Table Through a Module
What parts of OpenMRS does a module have access to override?
See Module Access
How can I set module level log4j properties?
Put "log4j.xml" in the metadata directory of the module
Why aren't my module classes loaded properly?
There is an issue for this in Trac. For a better explanation and temporary fix, see http://dev.openmrs.org/ticket/848.
What video how-to files are available?
[edit]

TODO

  • Requiring a specific version of another module
  • Implement business database knowledge
  • A clean unload option for "undiffing" and removing all of a module's privileges/global properties
Retrieved from "http://openmrs.org/wiki/Modules"