Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

Automatic Using the Maven Archetype

The easiest way to create a module is to Use the Module Maven Archetype.

It will create the project skeleton and a pom.xml file with all the dependencies for OpenMRS APIs and modules.

Video Guide from OpenMRS University

  1. Creating an OpenMRS Module using the Maven Archetype - Part 1
  2. Creating an OpenMRS Module using the Maven Archetype - Part 2
  3. Adobe Connect Playback

Manual Step by Step Instructions

There is really no reason to do anything other than use the maven archetype (see above), but if you want to create the module structure manually:

  1. Check out a local copy of the basicmodule using Maven (view source or view source in svn)
    1. (assumes you have m2eclipse installed in maven.  see Using the M2Eclipse Maven Plugin In Eclipse
    2. Right click on openmrs-modules/basicmodule/trunk openmrs svn repo, choose Check out as Maven Project
      1. Under advanced, uncheck 'separate projects for modules'
      2. Next to 'name template': enter your project/folder name. e.g. MyModuleX
      3. Click finish
  2. Disconnect the project from the database (you won't be checking your changes back in as the "BasicModule")
    1. Using Subclipse: right-click on the project name, select "Team->Disconnect..."
    2. "Confirm Disconnect from SVN" wizard appears
    3. select the "Also delete the SVN meta..." radio button
    4. click "Yes" button
  3. Replace all references to the Basic Module with your new modules name, using the same Conventions. (For example, rename BasicModule to MyFirstModule).
    1. edit omod/src/main/resources/config.xml
      1. find the "<id>" tag, edit the value (example: change "<id>basicmodule</id>" to " <id>myfirst</id>")
      2. find the <name> tag, edit the value (example: change "<name>Basic Module</name>" to "<name>My First Module</name>")
      3. find the <author> tag, change the value from Ben Wolfe to your name ... Ben shouldn't get all the credit
      4. find the <description> tag, edit the value if you want,
      5. you can change the <version> value, following the Versioning conventions
      6. find the <activator> tag, change the activator name.  Must be a class in your module. Case sensitive!
    2. edit omod/src/main/resources/moduleApplicationContext.xml
      1. This file is really only needed if you want either 1) your module to provide jsp files or 2) your module to have its own ___Service.java class
    3. edit omod/src/main/resources/liquibase.xml
      1. This is only needed if you are adding your own tables to the openmrs data model (or modifying others)
    4. rename the packages
      1. expand api/src/main/java
      2. right-click on org.openmrs.module.basicmodule "Refactor->Rename..."
      3. the "Rename Package" wizard appears
      4. edit the name (example: change to "org.openmrs.module.myfirst")
      5. select all of the check boxes (Put a * in the "File name patterns" text field)
      6. click "Preview"
      7. (wait patiently)
      8. click "OK" on the final screen of the wizard
    5. repeat the previous for omod/src/main/java and omod/src/test/java
    6. Be certain to rename all files that have BasicModule (or basicmodule) in their name (for example basicmoduleForm.jsp under web/module). Also look in the contents of the files (e.g. AdminList.java and build.xml)
    7. Change the contents of omod/src/main/resources/messages_*.properties
    8. Build your module using maven.  "mvn package" at command line or "right click on project, run as --> maven package"
  4. Try out your module
    1. Go to your openmrs installation Administration-->Manage Modules
    2. Choose Upload and browse to the "omod/target" folder in your checked out code. choose the latest.omod file
  5. Document your module
    • Modules should have a home page that describes their purpose, features, instructions, known issues, etc.
    • Feel free to create a wiki page for your module on this wiki. Your page should be called "FooBar Module" if you have created a module called FooBar.
    • Create it as a child of the Active Projects page
  6. Publish the resulting .omod file
  7. Committing your code to the OpenMRS subversion repository
    1. See Requesting Subversion Repository Access to get a new SVN project created for you.
    2. After a new SVN project has been created for you, the easiest way is to:
      • check out the new project that was created for you
      • then copy and paste your unattached code into that project
      • Then just commit that entire project

Old Instructions

These were the instructions used before the basicmodule was converted to maven.  If you are copying an old module or really don't want to use Maven, follow these.  Otherwise, we recommend using the above steps

Explicit step-by-step references presume you are working within Eclipse.

  1. Check out a local copy of the Basic Module from the repository: 
    http://svn.openmrs.org/openmrs-modules/basicmodule/trunk
    ## If given the option to set the project name, give it a module name using the same conventions.
  2. Disconnect the project from the database (you won't be checking your changes back in as the "BasicModule")
    1. Using Subclipse: right-click on the project name, select "Team->Disconnect..."
    2. "Confirm Disconnect from SVN" wizard appears
    3. select the "Also delete the SVN meta..." radio button
    4. click "Yes" button
  3. Replace all references to the Basic Module with your new modules name, using the same conventions. (For example, rename BasicModule to MyFirstModule).
    1. edit metadata/config.xml
      1. find the "<id>" tag, edit the value (example: change "<id>basicmodule</id>" to " <id>myfirst</id>")
      2. find the <name> tag, edit the value (example: change "<name>Basic Module</name>" to "<name>My First Module</name>")
      3. find the <author> tag, change the value from Ben Wolfe to your name ... Ben shouldn't get all the credit (wink)
      4. find the <description> tag, edit the value if you want, you can change the <version> value, following the versioning conventions
      5. find the <activator> tag, change the activator name
    2. edit metadata/moduleApplicationContext.xml
      1. This file is really only needed if you want either 1) your module to provide jsp files or 2) your module to have its own ___Service.java class
    3. edit metadata/sqldiff.xml
      1. This file is not needed if you are not adding/modifying any tables or columns in the openmrs datamodel
      2. find the <author> tag and edit the value.
      3. find the <date> tag and edit the value.
    4. rename the project (if you didn't set it during checkout)
      1. right-click on "BasicModule" in the "Package Explorer"
      2. select "Refactor->Rename..."
      3. enter the new name (example: change to "MyFirstModule")
    5. rename the packages
      1. expand src
      2. right-click on org.openmrs.module.basicmodule "Refactor->Rename..."
      3. the "Rename Package" wizard appears
      4. edit the name (example: change to "org.openmrs.module.myfirst")
      5. select all of the check boxes (Put a * in the "File name patterns" text field)
      6. click "Preview"
      7. (wait patiently)
      8. click "OK" on the final screen of the wizard
    6. Repeat the previous set of steps for web/src and test/
    7. Be certain to rename all files that have BasicModule (or basicmodule) in their name (for example basicmoduleForm.jsp under web/module). Also look in the contents of the files (e.g. AdminList.java and build.xml)
  4. Change the contents of metadata/messages_*.properties
  5. We recommend (and use) Eclipse IDE, but as long as you have Apache ANT installed, you can use a text editor if you prefer.
  6. Build your module (.omod file) using ANT (e.g., run <tt>ant package-module</tt> at command line in the root of the module)
  7. Try out your module
    1. Go to your openmrs installation Administration-->Manage Modules
    2. Choose Upload and browse to the "dist" folder in your checked out code. choose the latest.omod file
  8. Document your module
    • Modules should have a home page that describes their purpose, features, instructions, known issues, etc.
    • Feel free to create a wiki page for your module on this wiki. Your page should be called "FooBar Module" if you have created a module called FooBar.
    • Create it as a child of the Active Projects page
  9. Publish the resulting .omod file
  10. Committing your code to the OpenMRS subversion repository
    1. See Requesting Subversion Repository Access to get a new SVN project created for you.
    2. After a new SVN project has been created for you, the easiest way is to:
      • check out the new project that was created for you
      • then copy and paste your unattached code into that project
      • Then just commit that entire project
  • No labels