Flexible Method Signatures for UI Framework Controller and Action Methods
- Darius Jazayeri
- Gayan W.
- Michael Downey
- Janet Riley
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:
@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:
@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.