Customizing Name Layouts

Owned by Victor Garcia
Last updated: Dec 03, 2023 by Mujuzi Moses
2 min read

There are certain name layouts that come with OpenMRS right now, they are: short (default), long, givenfamily, latinamerica and spain.  These are stored in the openmrs-servlet.xml file. You can find this file in tomcathome/webapps/openmrs/WEB-INF/lib/openmrs-web...jar/openmrs-servlet.xml .

You can modify the layout.name.format  setting  (formerly global property from platform 1.8 downwards) to one of those values or to the "codeName" of a new custom layout (instructions below) to see a different name layout.

Description of existing name layouts

These are the name layouts that come with OpenMRS. The following table shows which items are contained in each of them (they are ordered from shortest to longest).



code

Prefix

Given Name

Middle Name

Family Name Prefix

Family Name

Family Name 2

Family Name Suffix

Degree 

code

Prefix

Given Name

Middle Name

Family Name Prefix

Family Name

Family Name 2

Family Name Suffix

Degree 

givenfamily



X





X







short 



X

X



X







spain 



X





X

X





latinamerica 



X

X



X 

X





long 

X 

X 

X 

X 

X 

X 

X 

X 

Adding/Overriding existing NameTemplate

  1. Add a new Global Property named "layout.name.template" if it already exists, update it's value to the your custom xml template: 

    <org.openmrs.layout.name.NameTemplate> <codeName>customXmlTemplate</codeName> <displayName>Custom Name Format</displayName> <nameMappings class="properties"> <property name="prefix" value="PersonName.prefix"/> <property name="givenName" value="PersonName.givenName"/> <property name="familyName" value="PersonName.familyName"/> </nameMappings> <sizeMappings class="properties"> <property name="prefix" value="5"/> <property name="givenName" value="30"/> <property name="familyName" value="25"/> </sizeMappings> <lineByLineFormat> <string>prefix</string> <string>givenName</string> <string>familyName</string> </lineByLineFormat> <requiredElements> <string>givenName</string> <string>familyName</string> </requiredElements> </org.openmrs.layout.name.NameTemplate>



  2. Change the nameMappings, sizeMappings, and lineByLineFormat elements however you like.

  3. Update the  layout.name.format  Global Property to the custom template's codeName so that it is chosen as the active template.



e.g. if you don't want to show prefix, you delete the lineByLineFormat line: <string>prefix</string>

e.g. if you want to have a longer givenName, you modify <property name="givenName" value="30"/> to be <property name="givenName" value="50"/>