2.x Module Compatibility

Overview

The 2.x application does not load the webModuleApplicationContext.xml file. It loads moduleApplicationContext.xml and ui2ModuleApplicationContext.xml.

1.x modules that don't use webModuleApplicationContext.xml will often "work" without modification in 2.x, in the sense that they will successfully start, and you can visit their URLs directly, but that's not really good enough.

If you want a module to work well in both the OpenMRS 1.x and 2.x applications, you should split configuration up into:

• moduleApplicationContext.xml: API-level configuration, e.g. Services, DAOs
• webModuleApplicationContext.xml: 1.x-specific web configuration
• ui2ModuleApplicationContext.xml: 2.x-specific web configuration, including extensions

How to expose a Spring MVC url as a 2.x Page

URLs that are handled by Spring MVC (either by XML- or Annotation-driven configuration) may be exposed as 2.x Pages using the SpringMvcPageViewProvider, which effectively does a jsp:include of the Spring page, and exposes that as a page.

In ui2ModuleApplicationContext.xml

<bean class="org.openmrs.ui2.core.page.PageFactory" autowire-candidate="false">
	<property name="additionalViewProviders">
		<map>
			<entry key="(your-module-id)-module">
				<bean class="org.openmrs.ui2.core.page.SpringMvcPageViewProvider">
					<property name="pages">
						<map>
							<entry key="pageNameIn2x" value="/module/(your-module-id)/(your-page).form" />
						</map>
					</property>
				</bean>
			</entry>
		</map>
	</property>
</bean>

If you don't want to include the entire page, you may put one or both of these in your JSP:

• <!- START 2.x PAGE CONTENT ->
• <!- END 2.x PAGE CONTENT ->

How to expose a Spring MVC url as a 2.x Fragment

URLs that are handled by Spring MVC (either by XML- or Annotation-driven configuration) may be exposed as 2.x Fragments using the SpringMvcPageAsFragmentViewProvider, which effectively does a jsp:include of the Spring page, and exposes that as a fragment, which can be included in other pages.

In ui2ModuleApplicationContext.xml

<bean class="org.openmrs.ui2.core.fragment.FragmentFactory" autowire-candidate="false">
	<property name="additionalViewProviders">
		<map>
			<entry key="(your-module-id)-pages">
				<bean
					class="org.openmrs.ui2.core.fragment.SpringMvcPageAsFragmentViewProvider">
					<property name="fragments">
						<map>
							<entry key="fragmentNameIn2x" value="/module/(your-module-id)/(your-page).form" />
						</map>
					</property>
				</bean>
			</entry>
		</map>
	</property>
</bean>

If you don't want to include the entire page, you may put one or both of these in your JSP:

• <!- START 2.x FRAGMENT CONTENT ->
• <!- END 2.x FRAGMENT CONTENT ->

You may use query parameters on map entry's values, but you must use

&

for &, like in this example from HTML Form Entry:

<entry key="lastHtmlForm" value="/module/htmlformentry/htmlFormEntry.form?pageFragment=true&amp;mode=VIEW&amp;which=last" />

How to Expose 1.x Content at a 2.x Extension

The 2.x application ignores the extensions defined in the module's config.xml file. But you may define extensions through ui2ModuleApplicationContext.xml like in this example, which exposes a page from the Growth Chart module as a patient dashboard fragment:

<!-- excerpt: see above for exactly how to do this -->
<bean class="org.openmrs.ui2.core.fragment.SpringMvcPageAsFragmentViewProvider">
	<property name="fragments">
		<map>
			<entry key="growthChartForm" value="/module/growthchart/growthChart.form"/>
		</map>
	</property>
</bean>
<!-- end excerpt -->

<bean id="growthChartPatientDashboardFragmentExtension" class="org.openmrs.ui2.core.extension.PatientFragmentExtension">
	<property name="fragment" value="growthChartForm" /> <!-- This refers to the fragment exposed in the excerpt -->
	<property name="label" value="Growth Chart" />
	<property name="description" value="Pediatric growth chart" />
</bean>

Redirects

For convenience, certain commonly URLs from 1.x are redirected to their appropriate pages in 2.x (preserving query strings):

• / -> /home.page
• /index.* -> home.page
• /patientDashboard.form -> /patient.page

1.x Technologies That Work in 2.x (when it's running in 1.x-compatibility mode)

• module resources
• DWR

Known Limitations

• <openmrs:fieldGen/> tag does not work in 2.x. (TRUNK-2489)
• <openmrs_tag:*/> do not work in 2.x. (We're not planning to fix this.)