All OpenMRS ID accounts have been reset.

Read more and change your password before signing in.
Icon

EXTENDED: OMRS14 Proposals due 30 April! Read more and submit a proposal at OpenMRS Talk.

Skip to end of metadata
Go to start of metadata

Introduction :

The purpose of this is to speed up developer startup time when creating modules. Creating a module is currently a laborious process that includes a lot of file renaming and copy/pasting from other module templates. This maven wizard helps a user to  walk directly in creating the different types of modules and naming things correctly. This  would help to at least speed up the initial creation time.

Icon

Note that this is the project page that described the process leading to the original development of the archetype.

For instructions on using the archtype, see Using the Module Maven Archetype.

Creation of modules using module-wizard-plugin :

All moudules start with a basic folder structure:

  • Basic OpenMRS Module

At present the developer has 2 additional options:

  • Module with admin page link as well as a controller and a jsp page for that link.  
  • Module with a Service , HibernateDAO , POJO , Hibernate mapping , liquibase.xml and sqldiff.xml 

See the detail instructions for creating a customized module.

Developing a Module Maven Plugin

For developing a module maven plugin there were few limitations:

Maven archetype plugin is not flexible in:

  • Creation of wizard
  • Selecting necessary module templates
  • Overriding files

As a solution maven-plugin , archetype-plugin and velocity conditions are combined together.

Archetype Plugin : Creates modules from the templates , known as archetype's.
Maven Plugin       : Plays the role of being  wizard i.e asking wizard questions and parametrize them so that they are available for archetype generation mechanism.

Example for developing fully featured archetype:

Aim :

To make module-wizard-plugin compatible in adding a link to openmrs admin page. 

Procedure :

1) Create partial archetype which adds  AdminList.java  file to a module-api.
2) Combine archetype with the WizardMojo  of module-wizard-plugin. 
3) Add velocity condition in " openmrs-archetype-basicmodule-creation" config.xml.

Steps :

1) Create partial archetype which adds  AdminList.java  file to a module-api.       

   By using partial property of  archetype , we can add files to the existing basic module.

   a)Checkout : http://svn.openmrs.org/openmrs-contrib/maven/archetypes/openmrs-archetype-module/branches/openmrs-partial-archetype-module/

    This is the basic partial archetype structure.   
   
   b) Rename your parent project folder
       openmrs-partial-archetype-module to openmrs-archetype-adminpagelink-creation

   c) Change artifactId and name tag values in  pom.xml (Path : openmrs-archetype-adminpagelink-creation\ )     

   d) Add required properties under <requiredProperties /> tag in archetype-metadata.xml (Path: openmrs-partial-archetype-module\src\main\resources\META-INF\maven\ )
      We use , module name(with and with out spaces) and admin page link as input parameter's.
      Syntax:  <requiredProperty key="" >
                          <defaultValue  ></defaultValue>   //with default value
                    </requiredProperty>
                                                      (  or  )
                    <requiredProperty key="" />              //with-out default value       

    e) Add all the required source files in archetype-resources folder of project. Source files under archetype-resources folder act like prototypes.
        Add "AdminList.java" file to Path: openmrs-archetype-adminpagelink-creation\src\main\resources\archetype-resources\api\src\main\java\extension\html\  .  

  

  f) Describe the list of all the files that are contained in the archetype-resources under <fileSets ></fileSets> tag , so that can be processed correctly by the archetype generation mechanism.

      <directory />  - This tag points a location starting from archetype-resources folder.
      " **/*.java "       -  Implies that  all the .java file's in parent and its sub-folders should be included.
 
  g) Clean/Remove the archetype-metadata.xml and non-required files and folders from project. 

  • omod folder in archetype resources in not required.
  • filset tag describing omod folder in archetype-metadata.xml is also not required.

Final project structure -
  h) Run mvn install on archetype-project to check whether it builds correctly or not.
    If " Build Success Full " message comes,  then your archetype is working and installed into your local maven repository .m2 .

2) Combine archetype with the WizardMojo  of module-wizard-plugin.

   a)Check out module-wizard-plugin
      URL: http://svn.openmrs.org/openmrs-contrib/maven/plugins/module-wizard-plugin/trunk/

   b)Add the required parameter's to WizardMojo.java
   

       -adminPageLink value can be  manipulated from command line.

       -adminLinkReply value cannot be manipulated with command line.

     c) Add the related question to wizard 
    Maven plugin uses plexus prompter for prompting questions in maven wizard.   

 We can prompt text in two patterns and it returns string
 String parameter1=prompter.prompt(  <command line prompting text >  );    //With out default value    
 String parameter2=prompter.prompt(  <command line prompting text >  , <default value is user enters null >);  //With default value  
Patient Name::             <returns null value>    
Patient Name: John : :  <on entering null ,it returns default value " John " >   

d)Adding question to WizardMojo.java
       -Asking  whether a user want a admin link or not , format (Y/N) .

       -Asking parameter values if admin link question is yes.

      e) Add the values as properties to maven session so that they are available for openmrs-archetype-adminpagelink-creation archetype
         As "module-name " , "module-name-no-spaces " are already set for basic basic module creation , we need to add admin-page-link to WizardMojo properties.
         Syntax   :  properties.setProperty( <property-name> , <value> );

          Note:  <property-name> is case sensitive

       f)Add the created archetype artifactId to archetypeIds of WizardMojo.java to execute the archetype.                  
        Note: openmrs-archetype-basicmodule-creation should be added first to parameter ' archetypeIds ' as parent archetype should be executed first before partial archetype executes.
        Run command "mvn install" on  module-wizard-plugin.
        It should give "Build Success Full" message.
 

3)Add velocity condition to " openmrs-archetype-basicmodule-creation " config.xml

       To add link to admin page ,we have to add extension tag in config.xml but archetype doesnot allow over-writing of files so by using velocity conditions we have to write them in basicmodule-archetype.
       a)Check out openmrs-archetype-basicmodule-creation
          URL : http://svn.openmrs.org/openmrs-contrib/maven/archetypes/openmrs-archetype-basicmodule-creation/trunk/

      b)Add condition property to archetype-metadata.xml <requiredProperties /> tag of " openmrs-archetype-basicmodule-creation " so that it is available for velocity condition
         Path : openmrs-archetype-basicmodule-creation\src\main\resources\META-INF\maven\

    c) Add adminList extension with velocity condition to " openmrs-archetype-basicmodule-creation " config.xml

     d) Run mvn install on openmrs-archetype-basicmodule-creation
        

To run the plugin:

1) Locate your command line to a empty directory.
2) Run maven command
    Syntax   : mvn <groupId>:<artifactid>:<version>:<goal>
    Example : mvn org.openmrs.maven.plugins:module-wizard-plugin:1.0-SNAPSHOT:generate
3) Follow the wizard (Build Success message must be seen)   

Icon

All the new archetypes should be committed inhttp://svn.openmrs.org/openmrs-contrib/maven/archetypes/$\{artifactId\}/trunk/

  • No labels