Flexible Method Signatures for UI Framework Controller and Action Methods

Owned by Darius Jazayeri
Last updated: Mar 27, 2017 by Gayan W.
3 min read

The UI framework has conventions for page and fragment controller classes and allows you to give flexible method signatures for page controller, fragment controller, and fragment action methods.

Page Controller method

  • page controller classes must be in the org.openmrs.module.yourmodule.page.controller package
  • the class name must be the page name (with its first letter uppercased) + "PageController"
  • depending on the request method, a controller methods named get(), post(), etc will be called. If the method doesn't exist and a controller() method does, that will be called (for all request methods)
  • for example the controller method for the "editEncounter" page is org.openmrs.module.uiexample.page.controller.EditEncounterPageController.controller()
  • in rare cases you may want to override these settings by manually configuring your controller and view providers instead of using the standard setup.

Parameters

Method parameters will be auto-set by type for these classes:

  • org.openmrs.ui.framework.page.PageContext
  • org.openmrs.ui.framework.page.PageModel (this is preferred for clarity, although Model and Map have the same effect)
  • org.openmrs.ui.framework.Model (this will be a PageModel)
  • java.util.Map (this will be a PageModel)
  • org.openmrs.ui.framework.page.PageRequest
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.http.HttpServletResponse
  • javax.servlet.http.HttpSession
  • org.openmrs.ui.framework.session.Session
  • org.springframework.context.ApplicationContext
  • org.openmrs.ui.framework.UiUtils

@RequestParam annotation

You may put the @org.springframework.web.bind.annotation.RequestParam annotation (from Spring MVC) on any parameter and the UI Framework will take the specified parameter from the HTTP request, and use Spring's ConversionService to convert it to the specified argument type. For example:

public void controller(@RequestParam("patientId") Patient patient) { ... }

@MethodParam annotation

The @org.openmrs.ui.framework.annotation.MethodParam annotation allows you to encapsulate complex logic in a method (similar to Spring's @ModelAttribute). The value of the MethodParam annotation should be the method name to call, and that method may have a flexible signature in the same way as the controller. For example:

public void controller(@MethodParam("buildPatient") Patient patient) { ... }
public Patient buildPatient(@RequestParam ...) { ... ; return patient }

@CookieValue annotation

The @org.springframework.web.bind.annotation.CookieValue annotation will look for a value in a cookie in the HttpServletRequest whose name is the value of the annotation, and use Spring's type conversion to convert it to the specified argument type. For example:

public void controller(@CookieValue("lastLoginLocation") Location lastLoginLocation) { ... }

@InjectBeans annotation

TODO

@BindParams annotation

TODO (does it work here?)

@Validate annotation

TODO (does it work here?)

Return Types

  • void (or returning null): will render the page model with the default view
  • java.lang.String: either a page view name, or "redirect:url"
  • org.openmrs.ui.framework.page.FileDownload: to download a file
  • org.openmrs.ui.framework.page.Redirect: alternative way to do a redirect

Fragment Controller method

  • fragment controller classes must be in the org.openmrs.module.yourmoduleid.fragment.controller package
  • the class name must be the fragment name (with its first letter uppercased) + "FragmentController"
  • the controller method must be called "controller"
  • for example the controller method for the "findPatient" fragment is org.openmrs.module.uiexample.fragment.controller.FindPatientFragmentController.controller()
  • in rare cases you may want to override these settings by manually configuring your controller and view providers instead of using the standard setup.

Parameters

Method parameters will be auto-set by type for these classes:

  • org.openmrs.ui.framework.fragment.FragmentContext
  • org.openmrs.ui.framework.page.PageContext
  • org.openmrs.ui.framework.fragment.FragmentConfiguration
  • org.openmrs.ui.framework.fragment.FragmentModel
  • org.openmrs.ui.framework.page.PageModel (good style is to name the parameter "sharedPageModel")
  • org.openmrs.ui.framework.fragment.FragmentRequest
  • org.openmrs.ui.framework.page.PageRequest
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.http.HttpServletResponse
  • javax.servlet.http.HttpSession
  • org.openmrs.ui.framework.fragment.FragmentFactory (this will probably disappear)
  • org.openmrs.ui.framework.UiUtils
  • org.openmrs.ui.framework.session.Session
  • org.springframework.context.ApplicationContext
  • javax.servlet.ServletContext

@FragmentParam annotation

You may put the @org.openmrs.ui.framework.annotation.FragmentParam annotation on any parameter and the UI Framework will take the specified parameter from the FragmentConfiguration, and use Spring's ConversionService to convert it to the specified argument type (if necessary). For example:

public void controller(@FragmentParam("obs") List<Obs> obs) { ... }

@MethodParam annotation

Behaves as described under Page Controllers

@CookieValue annotation

Behaves as described under Page Controllers

@InjectBeans annotation

TODO

@BindParams annotation

TODO (does it work here?)

@Validate annotation

TODO (does it work here?)

Return Types

TODO

Fragment Action method parameters

Any public method in a fragment controller class is accessible as a fragment action.

Parameters

Method parameters will be auto-set by type for these classes:

  • org.openmrs.ui.framework.fragment.FragmentActionRequest
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.http.HttpServletResponse (available since 3.11.0)
  • javax.servlet.http.HttpSession
  • org.openmrs.ui.framework.UiUtils
  • org.openmrs.ui.framework.session.Session
  • org.springframework.context.ApplicationContext
  • javax.servlet.ServletContext

@RequestParam annotation

You may put the @org.springframework.web.bind.annotation.RequestParam annotation (from Spring MVC) on any parameter and the UI Framework will take the specified parameter from the HTTP request, and use Spring's ConversionService to convert it to the specified argument type

  • for example:

    public void voidPersonName(@RequestParam("personNameId") PersonName pn) { ... }

@BindParams annotation

TODO

@Validate annotation

TODO

Return Types

To simply signal success or failure, you should return either:

  • org.openmrs.ui.framework.fragment.action.SuccessResult (used to indicate success, and that the page should reload)
  • org.openmrs.ui.framework.fragment.action.FailureResult (used to indicate failure, which typically reloads the page with an error message)

If you want to return an object (which will be converted to JSON or XML by the framework) just return a simple object. (I.e. you should not return an object with lazy hibernate collections, or cycles in its object graph.) To simplify a complex object, making it suitable to be returned from a fragment action method, use the org.openmrs.ui.framework.SimpleObject helper class and its fromObject and fromCollection utility methods.