Pitch: Replacement of Reference Application Style Guide with one based on TwitterBootstrap

Continuing the discussion from Kickstarting Integration of Twitter Boostrap for Ref App UI for 2.6:

I have finally been able to get my thoughts together in a draft coherent plan to this

Background and Overview

The OpenMRS reference application has developed and maintained its own style guide (https://demo.openmrs.org/openmrs/uicommons/styleGuide.page) which defines how elements are built and defined.

There is a need to therefore move to a style guide that is used by more web developers around the world, hence the choice of Twitter Bootstrap (http://getbootstrap.com/) as the foundation building blocks with the Reference Application look and feel as the default theme.

The benefits for this move are as follows:

  • Easier to define the structure of Open Web Apps (OWAs) and widgets that are used as the foundation blocks

  • Attracts more developers without learning curve of OpenMRS specific web application structure

  • Responsive functionality out of the box to support web and smartphone form factors

  • Enable the resources spent on maintaining and updating the style guide to be used elsewhere


However this will be a major change to the reference application with the potential to break existing distributions that depend on the reference application.

The migration is expected happen over the course of 3 Reference Application releases as follows:

  • 2.8

    • Twitter Bootstrap 4, although in beta is considered stable enough for use with no additional features and changes being added, being incorporated into the Reference Application, themed to provide the same look and feel
  • Reference application Style guide updated to work with Boostrap.

  • Responsive pages introduced on the clinician facing dashboard, dashboard widgets updated to match the new styling

  • 2.9

    • Migration of OWAs and JS Widgets to the new HTML format for Boostrap begins
    • The Reference Application style guide marked as deprecated
  • 2.10 - final cut over to Bootstrap to replace Reference application style guide

An initial POC has been implemented by @darius as per this thread which can form the foundation of efforts being implemented Kickstarting Integration of Twitter Boostrap for Ref App UI for 2.6



As users of a distribution build on the reference application, we are greatly interested in this… I know we’d had many discussions of how we’d like to see the UI improved but have never had time to implement (not to mention that none of us here at PIH are UI or front-end specialists).

Of course, we’d also be concerned about any breaking changes, but are certainly willing to go through some adaptations if it leads to a better design. It’s easy for us to test and run snapshot versions of any modules in our CI pipeline, so it should be easy for us to test any changes and provide feedback.

I know that one of the biggest pet peeves is the fixed screen width, which leaves a lot of wasted space on high-resolution monitors.

EDIT: oh, and thanks for taking this on! :slight_smile:

Take care, Mark

1 Like

Hi Stephen, I recently joined the OpenMRS team so I don’t have that much info about the history of the project in terms of UI but I strongly support the move to Bootstrap 4, the Bootstrap team made a lot improvements on the UI to give it a cleaner and prettier feel in terms of the theme-ing, typography etc I’ve gotten to work with all the previous versions of bootstrap but after trying out version 4 I felt the difference and I loved it.

As for the breaking changes, to avoid that we could write unit tests and some snapshot tests too to at least minimize the breaking changes.

I think moving to Bootstrap is a fantastic idea. We should also put into consideration that Bootstrap uses jquery. Since a lot of the OWA’s are currently being developed using ReactJS, I’m assuming React will also be used here. From my experience, trying to use both React and jQuery could really be a pain

@joelakwes OpenMRS already has JQuery aliased to jq within the client interface so this should not be a problem

I’m aware that OpenMRS already has jQuery included. I’m only pointing out that if ReactJS is going to be used on the project, we might experience some issues as jQuery manipulates the DOM directly while React’s manipulation is on the virtual DOM

Welcome to #Javascript ■■■■, but I am confident that OpenMRS is not the first project to grapple with the JQuery/React issue so we can learn from others as we move forward.

A constraint is just a stepping stone to progress


Moving to Bootstrap is a good Idea, you should also look into Bootstrap that is optimized for specific frameworks ie https://ng-bootstrap.github.io for angular, https://react-bootstrap.github.io/ for react and https://v4-alpha.getbootstrap.com/ for the ones who are still using Jquery. They all implement the same styles just optimized to work better with the framework you are using


@ssmusoke did you just forget to include the spike link in your post?

@dkayiwa oops @darius carried out an initial spike here Kickstarting Integration of Twitter Boostrap for Ref App UI for 2.6 which can form the basis of additional exploration on this migration

Also I would like to recommend using Boostrap 4.0.0 which although is in beta has been feature frozen with only bug fixes coming along. So by the time this replacement is done (hopefully in 2-3 months) a stable release will have been made forming a foundation for the future

@ssmusoke that’s Bootstrap4.0.0-alpha.6 right?

Nope 4.0.0-beta2

Thanks for the clarification. Had misunderstood your earlier comment. Was working with beta and had rolled back

Christine please do keep sharing updates on your progress, blockers decisions needed etc

@ssmusoke FWIW I for one had not worked with reference application until recently and to say the least I had trouble grappling with the style guide. This initiative is good and indeed it will easy the pain for beginners and pros alike because lets face it, bootstrap is a de-facto style guide of the web now days.


Sure @ssmusoke, will be sending templates for review soon, latest tomorrow.

1 Like

Hey @ssmusoke, I have tried to replicate the style guide elements here by overriding bootstrap styles in custom_mixins.scss and custom_variables.scss. This way, one can use the normal bootstrap classes and still achieve the OpenMRS look. There is still a long way to go because I’m sure the customization can be done better, maybe by having all customization changes in one file. There is a challenge though with the non-comprehensive documentation for Bootstrapv4.0.0-beta2

However, achieving full functionality for all components may only be possible for apps developed using jQuery. For frameworks like angular and react, there may be need to include ng-bootstrap and reactstrap respectively or write additional functions to cater for functionality of components like tabs, dialog boxes etc.

The teams’ plan is to have one file dealing with all the customization so that it can be included in the generator repo for scafolding

cc: @dkayiwa, @kwahalf, @adams, @dbamidele

@nagadya I would like to suggest the following approach:

  1. Have the base Boostrap installation and setup with the default theme - unchanged to ease upgrades as new versions are released

  2. Build a new theme Reference Application which mimics the current look and feel. Unfortunately the output of the current widgets cannot be changed much since there are implementations out there that depend on this being possible.

  3. The ng-boostrap and reactstrap have to be added separately since the Reference application is meant to support both React and Angular.

  4. Overall I am thinking we may need to add a feature toggle uiframework.usebootstrap - which is false by default but turns on the use of Boostrap allowing for some overrides to be done.

In summary, rather than add everything into a single file the approach is to provide ability to enable other implementations to override the themes provided by Reference Application.

I hope this helps, happy to jump on a call to brainstorm alternate approaches

A brainstorming call sounds perfect @ssmusoke. Let us know when you’ll be available so we can have one.

@nagadya We can have one at the top of the hour @dkayiwa I think we can use https://www.uberconference.com/openmrs