{"type":"doc","content":[{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"maxLevel":{"value":"3"},"outline":{"value":"true"}},"macroMetadata":{"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Pages and Fragments","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Controller classes","type":"text"}]},{"type":"paragraph","content":[{"text":"Unlike Spring controllers, UI Framework controllers are not components. To enable the development mode, controller classes are reloaded from the file system for each request, so they have no state and no static ","type":"text"},{"text":"state","type":"text","marks":[{"type":"textColor","attrs":{"color":"#444444"}}]},{"text":" across ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#444444"}}]},{"text":"instances.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#444444"}}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Because of the dynamic nature of controller classes one should be careful not to rely on the state of static variables within controller class. The instanceof keyword will also not function as expected when working with controller classes.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Controller method parameters","type":"text"}]},{"type":"paragraph","content":[{"text":"You may have zero or one of these annotations (and they are applied first):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"@RequestParam","type":"text","marks":[{"type":"strong"}]},{"text":": gets the argument value from an HttpServletRequest parameter","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"supports type conversion","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"@FragmentParam","type":"text","marks":[{"type":"strong"}]},{"text":"(only for Fragment controllers): gets the argument value from a FragmentConfiguration","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"supports type conversion","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"@SpringBean","type":"text","marks":[{"type":"strong"}]},{"text":": gets the argument value from Spring's application context. Behaves like @Autowired; if you give an annotation value, that behaves like @Qualifier","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"@CookieValue","type":"text","marks":[{"type":"strong"}]},{"text":": gets the argument value from a cookie in the HttpServletRequest","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"supports type conversion","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"If the above annotations did not produce a non-null value, and the argument has a ","type":"text"},{"text":"@MethodParam","type":"text","marks":[{"type":"strong"}]},{"text":" annotation, then the method named in the annotation's value will be called to instantiate the argument.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"@InjectBeans","type":"text","marks":[{"type":"strong"}]},{"text":" annotation is present, then we use Spring to set any properties on the argument marked with @Autowired. (If no previous annotation produced a non-null value for the argument, then the no-arg constructor on the argument class will be called.)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"@BindParams","type":"text","marks":[{"type":"strong"}]},{"text":" annotation is present, then any request parameters that match properties on the argument class will be automatically type-converted and set on the argument object. (If no previous annotation produced a non-null value for the argument, then the no-arg constructor on the argument class will be called.)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"@Validate","type":"text","marks":[{"type":"strong"}]},{"text":" annotation is present, then we fetch the preferred Validator (from the Spring application context) for the argument class, and use this to validate the argument value. Any validation errors will lead to a BindParamsValidationException being thrown, and the controller method will not be called.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"A (contrived) example showing the most annotations you can use together","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"public class ExamplePageController {\n public void get(@RequestParam(value = \"patientId\", required = false) @MethodParam(\"ifNotSpecified\") @InjectBeans @BindParams @Validate PatientWrapper wrapper) {\n // ...\n }\n\n public PatientWrapper ifNotSpecified() {\n return new PatientWrapper(new Patient());\n }\n}\n\npublic class PatientWrapper {\n private Patient patient;\n @Autowired private VisitService visitService;\n\n public void setPatient(Patient patient) {\n // ...\n }\n\n public void setAge(Integer age) {\n // ...\n }\n\n public List getVisits() {\n return visitService.getVisitsByPatient(patient, true, false);\n }\n}\n\n@Component\npublic class PatientToPatientWrapperConverter implements Converter {\n // ...\n}\n\n@Validator(PatientWrapper.class)\npublic class PatientWrapperValidator implements Validator {\n // ...\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Page request interceptors","type":"text"}]},{"type":"paragraph","content":[{"text":"These provide a mechanism for intercepting all page requests and performing some logic before the request is handled by the page controller. An interceptor is any component which extends PageRequestInterceptor.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of using an interceptor to check user authentication","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"@Component\npublic class RequireLoginPageRequestInterceptor implements PageRequestInterceptor {\n\t@Override\n\tpublic void beforeHandleRequest(PageContext context) {\n\t\tif (!Context.isAuthenticated()) {\n\t\t\tthrow new APIAuthenticationException(\"Login is required\");\n\t\t}\n\t}\n} ","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Formatting","type":"text"}]},{"type":"paragraph","content":[{"text":"Throughout the UI Framework, wherever you have access to a UiUtils object, you can format a wide variety of objects to a String, using UiUtils.format(Object).","type":"text"}]},{"type":"paragraph","content":[{"text":"This covers most OpenMRS objects, as well as Dates.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Date formatting","type":"text"}]},{"type":"paragraph","content":[{"text":"The default format for dates whose time component is 00:00:00.000 is \"01.Feb.2003\" and the default format for dates with a meaningful time component is \"01.Feb.2003, 14:25:36\".","type":"text"}]},{"type":"paragraph","content":[{"text":"Since version 2.5 you can change the format used by setting the global properties ","type":"text"},{"text":"uiframework.formatter.dateFormat","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"uiframework.formatter.dateAndTimeFormat","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Changing formatter implementations","type":"text"}]},{"type":"paragraph","content":[{"text":"Since version 3.3 you can override the built-in formatting for different types at an installation-wide level by defining a Spring bean that describes how to format each class. Currently we support only Handlebars templates, but other templating technologies could be added.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Custom Handlebars Formatters","type":"text"}]},{"type":"paragraph","content":[{"text":"Define a spring bean for each class whose formatting you want to override. The implementation is ","type":"text"},{"text":"handlebars.java","type":"text","marks":[{"type":"link","attrs":{"href":"http://jknack.github.io/handlebars.java/"}}]},{"text":", and we support two additional helpers:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"{{format propertyName}}","type":"text","marks":[{"type":"code"}]},{"text":" ... recursively applies formatting to the specified property","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"{{message 'code'}}","type":"text","marks":[{"type":"code"}]},{"text":" ... localizes the given message code","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"add this to a moduleApplicationContext.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n {{format encounterType}} {{message 'general.at'}} {{format location}} ({{message 'general.onDate'}} {{format encounterDatetime}})\n \n","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Localization","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Messages","type":"text"}]},{"type":"paragraph","content":[{"text":"Throughout the UI Framework, wherever you have access to a UiUtils object you can use the message(String code, Object... args) method, which delegates to the Spring MessageSource, with the current locale.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"// in a GSP\n${ ui.message(\"helloUser\", loggedInUser.person.personName) }\n\n// in a page controller\npublic String post(..., UiUtils ui) {\n ...\n return new SuccessResult(ui.message(\"yourmoduleid.action.successMessage\"));\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Localizing metadata (since version 2.5)","type":"text"}]},{"type":"paragraph","content":[{"text":"Since OpenMRS core does not have support for localizing metadata, the UI Framework provides a mechanism to do this. You can define certain specific localized messages that the UI Framework's formatter will use in preference to a metadata's name property.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"// in a module's messages.properties file\nopenmrs.property.MESSAGE_PROPERTY_ALLOW_KEYS_OUTSIDE_OF_MODULE_NAMESPACE = true\nui.i18n.PatientIdentifierType.name.e66645eb-03a8-4991-b4ce-e87318e37566 = Dossier Number\n\n// in a GSP\n${ ui.format(patient.patientIdentifier) }\n\n// will output something like:\nDossier Number = ABC123\n","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Versions of OpenMRS prior to 1.9.3 do not allow modules to define messages outside of their namespace, so to provide suitable messages you would have to use the Custom Messages module, or define a custom MessageSource.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"As of version 3.0, you can use this mechanism to override the names of concepts. As concepts already have support for localization in the OpenMRS API, this use of UI Framework localization is only recommended for users of shared concept dictionaries who are not able to modify concept names in the database.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Including resources","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How do I include a js or css file globally on every page?","type":"text"}]},{"type":"paragraph","content":[{"text":"You can define resources to be available on every pages of the application by adding a Spring bean that describes the resource to include.","type":"text"}]},{"type":"paragraph","content":[{"text":"For instance, to include the ","type":"text"},{"text":"myStyle.css","type":"text","marks":[{"type":"em"}]},{"text":" file, located in the directory ","type":"text"},{"text":"mymodule/omod/src/main/webapp/resources/styles/ ","type":"text","marks":[{"type":"strong"}]},{"text":", simply edit the ","type":"text"},{"text":"webModuleApplicationContext.xml","type":"text","marks":[{"type":"em"}]},{"text":" file of your module and add:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of including CSS to the application","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"Notes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The \"","type":"text"},{"text":"resourcePath","type":"text","marks":[{"type":"em"}]},{"text":"\" property is implicitly prefixed by ","type":"text"},{"text":"mymodule/omod/src/main/webapp/resources/","type":"text","marks":[{"type":"strong"}]},{"text":" (because of the value we set for ","type":"text"},{"text":"\"providerName\"","type":"text","marks":[{"type":"em"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The \"","type":"text"},{"text":"priority","type":"text","marks":[{"type":"em"}]},{"text":"\" property will define in which order resources are loaded (a high priority resource will be included before a low priority resource; for css, as in this example, files loaded later take precedence, so a lower priority will have greater effect)","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"See org.openmrs.ui.framework.page.GlobalResourceIncluder. (Added in 2.1)","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"webModuleApplicationContext.xml","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-module-referenceapplication/blob/master/omod/src/main/resources/webModuleApplicationContext.xml"}}]},{"text":" in the referenceapplication module for a live example.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Styling","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How do I use Compass and Sass to write CSS more easily?","type":"text"}]},{"type":"paragraph","content":[{"text":"See how PIH has incorporated this in the Mirebalais module. Look for \"compass\" in ","type":"text"},{"text":"omod/pom.xml","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/PIH/openmrs-module-mirebalais/blob/master/omod/pom.xml"}}]},{"text":" (TODO point this to a reference application usage).","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you have set up the pom files as in (that module) then css files will be generated automatically as part of a maven build, during the \"process-resources\" phase. If you're going to be making iterative changes to your module's scss files, you can do:","type":"text"}]},{"type":"codeBlock","content":[{"text":"mvn process-resources -Pwatch-sass","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"XSS Prevention","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"What is XSS?","type":"text"}]},{"type":"paragraph","content":[{"text":"XSS is a common web application vulnerability that allows an attacker to execute arbitrary javascript in the context of users who visit a vulnerable web page. XSS can lead to website defacement, compromised administrative accounts, and even client browser exploitation. For more information, check out OWASP’s XSS page: ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)"}},{"type":"textColor","attrs":{"color":"#1155cc"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"XSS Case Studies","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Case Study #1: alert('XSS');","type":"text","marks":[{"type":"strong"},{"type":"textColor","attrs":{"color":"#ff0000"}}]},{"text":". In this case, the gsp script will generate the following HTML:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"

\n\tperson address line 1
\n\tperson address line 2
\n\t\n

","type":"text"}]},{"type":"paragraph","content":[{"text":"When a client next visits a page that includes formatAddress.gsp, the attacker's javascript will execute in the client's browser. The javascript alert is only a placeholder. An attacker would be able to insert any kind of malicious javascript if he/she is able to edit a patient address.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Case Study #2: HTML attribute injection","type":"text"}]},{"type":"paragraph","content":[{"text":"Another common xss injection point is in HTML attributes. Consider the following code snippet:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"groovy"},"content":[{"text":"

${ui.encodeHtmlContent(ui.format(it))}

","type":"text"}]},{"type":"paragraph","content":[{"text":"This snippet comes from login.gsp in the referenceapplication module. Here, if the attacker attempts to inject ","type":"text"}]},{"type":"paragraph","content":[{"text":"This snippet comes from patientSearchWidget.gsp in the coreapps module. An attacker who is able to edit a patient's name, could inject the following string: ","type":"text"},{"text":"\" \\n}\\n alert('XSS'); \\n/*","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":". This would result in the gsp script generating the following javascript:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"On most browsers, the attacker-supplied alert('XSS') code would be executed when a client visits a page the incorporates the patientSearchWidget.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"UI Framework Filtering Functions","type":"text"}]},{"type":"paragraph","content":[{"text":"The UI Framework includes a number of functions to filter untrusted user input and prevent XSS.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"String encodeHtmlContent(String input)","type":"text","marks":[{"type":"strong"}]},{"text":" - This function allows untrusted data to be safely displayed in HTML. This is mainly achieved by converting ","type":"text"},{"text":"<","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" and ","type":"text"},{"text":">","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" symbols to ","type":"text"},{"text":"<","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" and ","type":"text"},{"text":">","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" respectively. This kind of filtering will prevent XSS similar to case study #1","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"String encodeHtmlAttribute(String input)","type":"text","marks":[{"type":"strong"}]},{"text":" - This function allows untrusted data to be safely displayed in HTML attributes. This is mainly achieved by converting ","type":"text"},{"text":"\"","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"'","type":"text","marks":[{"type":"strong"},{"type":"textColor","attrs":{"color":"#ff0000"}}]},{"text":" symbols to ","type":"text"},{"text":""","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" and ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333366"}}]},{"text":"'","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"strong"}]},{"text":" respectively. This kind of filtering will prevent XSS similar to case study #2","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333366"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"String encodeJavaScript(String input)","type":"text","marks":[{"type":"strong"},{"type":"textColor","attrs":{"color":"#333366"}}]},{"text":" - This function allows untrusted data to be safely displayed in dynamically generated JavaScript. This is mainly achieved by using javascript backslash-escaping. This kind of filtering will prevent XSS similar to case study #3","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333366"}}]}]}]}]},{"type":"paragraph","content":[{"text":"It is important to note that the three case studies presented above do not represent all classes of XSS vulnerabilities. XSS is a notoriously difficult bug to prevent. Front-end developers should be imaginative and thorough when testing for it.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333366"}}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}],"version":1}