{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The OpenMRS UI Framework is packaged in a module which provides the ","type":"text"},{"text":"framework","type":"text","marks":[{"type":"em"}]},{"text":". To use it, you need to create a module of your own that depends on it and uses it.","type":"text"}]}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":3},"content":[{"text":"Depending on the UI Framework module","type":"text"}]},{"type":"paragraph","content":[{"text":"Its recommended that you use a mavenized module and that you generate it with the ","type":"text"},{"text":"Module Maven Archetype","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25481039"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"To refer to the UI Framework in your module, you just need a standard ","type":"text"},{"text":"module dependency","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25465691"}}]},{"text":" on ","type":"text"},{"text":"uiframework","type":"text","marks":[{"type":"em"}]},{"text":" module:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In your module's root pom.xml you need something like this: (you want to get the latest released version number from ","type":"text"},{"text":"http://mavenrepo.openmrs.org/nexus/index.html#nexus-search;quick~uiframework-api","type":"text","marks":[{"type":"link","attrs":{"href":"http://mavenrepo.openmrs.org/nexus/index.html#nexus-search;quick~uiframework-api"}}]},{"text":" )","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\t\n\t\t\n\t\t\n\t\t\torg.openmrs.module\n\t\t\tuiframework-api\n\t\t\t3.2.2\n\t\t\tjar\n\t\t\tprovided\n\t\t\n\t\t...\n\t\n\n","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In your module's omod/pom.xml you need something like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\torg.openmrs.module\n\tuiframework-api\n\n","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"And your module's omod/src/main/resources/config.xml needs something like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\t\n\t\torg.openmrs.module.uiframework\n\t\n\n","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Of course any administrator who installs your module will also have install the UI Framework module, just like with any other module dependency.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Beans in webModuleApplicationContext.xml","type":"text"}]},{"type":"paragraph","content":[{"text":"99% of of the time you'll want to have your module use the standard conventional configuration, by defining a single bean in webModuleApplicationContext.xml","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\t\t\n\t\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The standard configuration looks for:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java page controllers in org.openmrs.module.yourmoduleid.page.controller","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Groovy page views in your omod's web/module/pages","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java fragment controllers in org.openmrs.module.yourmoduleid.fragment.controller","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Groovy fragment views in your omod's web/module/fragments","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"Folders and Packages","type":"text"}]},{"type":"paragraph","content":[{"text":"In the 99% case where you're using this standard configuration, you should create the folders:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(yourmodule)/omod/src/main/webapp/pages","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(yourmodule)/omod/src/main/webapp/fragments","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(yourmodule)/omod/src/main/webapp/resources","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"And you should create your page and fragment controller packages like:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"org.openmrs.module.(yourmoduleid).page.controller at (yourmodule)/omod/src/main/java/org/openmrs/module/(yourmoduleid)/page/controller","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"org.openmrs.module.(yourmoduleid).fragment.controller at (yourmodule)/omod/src/main/java/org/openmrs/module/(yourmoduleid)/fragment/controller","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Development mode","type":"text"}]},{"type":"paragraph","content":[{"text":"The UI Framework supports a \"development mode\" that helps you iterate rapidly on web-layer functionality, by automatically recompiling controllers as you edit them, and automatically reloading views. Note that development mode only automatically recompiles ","type":"text"},{"text":"controllers","type":"text","marks":[{"type":"em"}]},{"text":" (for pages or fragments), not other classes. But you should be iterating on your module's domain objects and service layer using the unit testing framework anyway. :-)","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"OpenMRS SDK users","type":"text"}]},{"type":"paragraph","content":[{"text":"If your development environment is setup using the ","type":"text"},{"text":"OpenMRS SDK","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/OpenMRS+SDK"}}]},{"text":", then this step is even easier for you. All you need to do to enable UI framework development mode is run","type":"text"}]},{"type":"codeBlock","content":[{"text":"mvn openmrs-sdk:watch -DserverId=myserver","type":"text"}]},{"type":"paragraph","content":[{"text":"For more information on that see the ","type":"text"},{"text":"Watch projects","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/OpenMRS+SDK#OpenMRSSDK-Watchingprojects"}}]},{"text":" section of the SDK documentation.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Manual configuration(Non SDK users)","type":"text"}]},{"type":"paragraph","content":[{"text":"If you are not currently using the SDK for development(which we strongly recommend that you do), then follow these instructions instead.","type":"text"}]},{"type":"paragraph","content":[{"text":"To enable development mode for a particular module, you need to set an argument at runtime before starting up OpenMRS.","type":"text"}]},{"type":"paragraph","content":[{"text":"The primary means for doing this has been to set a VM argument on the JRE you are running OpenMRS in. (See section on Setting a VM argument below)","type":"text"}]},{"type":"paragraph","content":[{"text":"If you set the following VM argument, it will be picked up by the view and controller providers configured by the StandardModuleUiConfiguration bean for yourmoduleid.","type":"text"}]},{"type":"codeBlock","content":[{"text":"-DuiFramework.development.yourmoduleid=\"/path/to/root/of/mavenized/yourmoduleid\"\n","type":"text"}]},{"type":"paragraph","content":[{"text":"As of version 3.3 of the uiframework module, there some alternative options available for configuring development mode:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You can now specify any of the runtime arguments via either VM arguments (as described above), or as properties in your OpenMRS runtime properties file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You can continue to specify each individual module that you wish to put into development mode by listing it and the path to the code for it explicitly as described above","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For developers who want to more easily enable development mode for several modules that are checked out into a common location on the filesystem, you can specify","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"uiFramework.developmentFolder=/path/to/parent/folder/for/modules \nuiFramework.developmentModules=comma,separated,module,ids,to,include","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"This will work only if you have your code checked out into a directory named either or openmrs-module-","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"As an example, lets say that I manage all of my OpenMRS code in a single directory: /home/openmrs/code","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"Then, within that directory I have various modules cloned that I work on:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/home/openmrs/code/openmrs-module-coreapps","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/home/openmrs/code/openmrs-module-reportingui","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/home/openmrs/code/openmrs-module-htmlformentryui","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/home/openmrs/code/openmrs-module-appointmentschedulingui","type":"text"}]}]}]}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"If I set the following in my openmrs-runtime.properties file:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"uiFramework.developmentFolder=/home/openmrs/code","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"Then starting up my system, if any modules with moduleId in coreapps, reportingui, htmlformentryui, or appointmentschedulingui are started, then development mode will be enabled for these.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"However, if at the moment I am only working on coreapps and reportingui, and so I only want to enable development mode for these, then I can further limit this with the following in my openmrs-runtime.properties file:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"uiFramework.developmentFolder=/home/openmrs/code","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"uiFramework.developmentModules=coreapps,reportingui","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"This will also work as if my code is checked out under simply the moduleId (i.e. /home/openmrs/code/coreapps)","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting a VM argument","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Eclipse you can do this from the JRE tab of your ","type":"text"},{"text":"jetty:run","type":"text","marks":[{"type":"link","attrs":{"href":"http://jettyrun"}}]},{"text":" Run Configuration. In Eclipse, you need to specify this as: -DuiFramework...","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Netbeans you can do this by adding it to the ","type":"text"},{"text":"jetty:run custom goal","type":"text","marks":[{"type":"em"}]},{"text":". In detail, download/open the OpenMRS core source in Netbeans, then open the ","type":"text"},{"text":"openmrs-webapps","type":"text","marks":[{"type":"em"}]},{"text":" subproject. Right click on the webapps subproject, select ","type":"text"},{"text":"Custom/Goals","type":"text","marks":[{"type":"em"}]},{"text":"... This will bring up the ","type":"text"},{"text":"Run Maven","type":"text","marks":[{"type":"em"}]},{"text":" popup. Type ","type":"text"},{"text":"jetty:run","type":"text","marks":[{"type":"em"}]},{"text":" in the Goals and the VM argument line in the ","type":"text"},{"text":"Properties","type":"text","marks":[{"type":"em"}]},{"text":" text area of the goal by typing the following: ","type":"text"},{"text":"uiFramework.development.yourmoduleid=/path/to/root/of/mavenized/yourmoduleid","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Troubleshooting: ","type":"text","marks":[{"type":"strong"}]},{"text":"It is reported that in unix you may need to delete \" from the path and escape whitespaces with \\ if any.","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}],"version":1}

Browser not supported