Module Extension Points

Modules can extend the presentation layer through extension points. In an ideal world, modules would be able to modify the presentation layer with the same Aspect Oriented Programming (AOP) technique used for the API. However, the main presentation layer is currently via the webapp and html. There isn't currently a way to inject code in a general way into a jsp or html file.

Instead, Extension Points must be placed throughout the webapp to provide "hooks". Modules then create Extensions that hook into those points. A module can hook into any number of points any number of times. Each Extension must be defined in the config.xml file.

Extensions must extend the abstract class org.openmrs.module.web.Extension. If the getOverrideContent(String) returns a non-null, the returned value is inserted as the content for that extension.

For the webapp, the getMediaType() should always return Extension.MEDIA_TYPE.html or null. If generic display code is being returned, the media type can be null. The webapp will look for defined extension points that are either defined to be any (null) or html. In the future, when we have more than one type of presentation layer, we can have multiple MEDIA_TYPE options. (For now, the only one is html).

Contents

[edit]

Example: Adding an Extension to a module (adding section to the admin screen)

Tags inserted into the config.xml file: 

<extension>
	<point>org.openmrs.admin.list</point>
	<class>org.openmrs.module.formentry.extension.html.FormEntryAdminExt</class>
</extension>

The org.openmrs.admin.list Extension Point is defined in the /openmrs/admin/index.jsp file. This is one of several unique extension points that require certain methods to be implemented. The admin.list point requires a getTitle() method and a getLinks() method as defined in org.openmrs.module.web.extension.AdministrationSectionExt. (To insure validity, your Extension can simply extend this abstract class. To create an api/jar/library that you can include in your module, use the package-web-src option in the core ant build script. A web-openmrs-api-*.jar file will be created in the /dist folder).

The FormEntryAdminExt class is similar to: 

package org.openmrs.module.formentry.extension.html;

import java.util.Map;
import java.util.TreeMap;

import org.openmrs.module.Extension;
import org.openmrs.module.web.extension.AdministrationSectionExt;
import org.openmrs.util.InsertedOrderComparator;

public class FormEntryAdminExt extends AdministrationSectionExt {

	public Extension.MEDIA_TYPE getMediaType() {
		return Extension.MEDIA_TYPE.html;
	}
	
	public String getTitle() {
		return "formentry.title";
	}
	
	public Map<String, String> getLinks() {
		
		Map<String, String> map = new TreeMap<String, String>(new InsertedOrderComparator());
		
		map.put("module/formentry/xsnUpload.form", "formentry.xsn.title");
		map.put("module/formentry/formEntryQueue.list", "formentry.FormEntryQueue.manage");
		map.put("module/formentry/formEntryInfo.htm", "formentry.info");
		
		return map;
	}
	
}
[edit]

Example: Adding an Extension Point

At the very core, an Extension Point is simply a unique text string that defines a location that information can be inserted. An Extension Point can be in either the core OpenMRS presentation layer or in a module's presentation layer.

The simplest Extension Point simply requires it's extensions to use the getOverrideContent(String) method: 

<openmrs:extensionPoint pointId="org.openmrs.login" />

(In the OpenMRS webapp, the openmrs:extensionPoint taglib defaults to type="html")

A more complicated Extension Point might want more than one method implemented for complicated information: 

<openmrs:extensionPoint pointId="org.openmrs.admin.users.localHeader" type="html">
		<c:forEach items="${extension.links}" var="link">
			<li <c:if test="${fn:endsWith(pageContext.request.requestURI, link.key)}">class="active"</c:if> >
				<a href="${pageContext.request.contextPath}/${link.key}"><spring:message code="${link.value}"/></a>
			</li>
		</c:forEach>
</openmrs:extensionPoint>

The extension points in the local headers of each admin section expect the getLinks() method to be implemented in the Extensions. This is done to ensure the proper layout on the admin screen. Of course, the Extension can be obstinate and use the getOverrideContent(String) method to put whatever it wants in there.

[edit]

Where are there extension points currently?

The most sure and up-to-date way to find extension points is to look on the page that you want to extend. Look through the jsp files in the source code.

You can also search openmrs's code via a Google search for extensionPoint site:dev.openmrs.org/browser/openmrs/trunk

If the page you want to add something to does not have an extensionPoint on it, create a ticket or email the developers list asking for one.

[edit]

What kinds of abstract classes for extensions are there and what are they for?

[edit]

FAQ

My portlet (loaded via e.g. PatientDashboardTabExt, BoxExt) uses a custom PortletController, but I cannot access my custom data added by the controller.
Try changing your module's processing order in moduleApplicationContext.xml (lower number means earlier processing, default is 99): 
     <bean id="inpatientcareUrlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="order"><value>2</value></property>
...
</bean>
Retrieved from "http://openmrs.org/wiki/Module_Extension_Points"