Update on the replacement of the Reference Application Style Guide with Twitter Bootstrap

As discussed on this thread, plans are underway to replace the Reference Application Style Guide with Twitter Bootstrap specifically Bootstrapv4.0.0-beta2. Recently a team of four apprentices from Andela (@kwahalf, @adams, @dbamidele and I) started a spike to kickstart this process. Below are the discoveries we made.

  1. Theming in Bootstrap 4 is accomplished by “Sass variables, Sass maps, and custom CSS.” This required “additional tooling such Sass compiler for compiling the CSS.

  2. The reference application currently uses gem sassv3.2.5 which unfortunately cannot transpile mixins, a major component of bootstrap 4. It requires gem sassv3.3 or higher.

    Attempts to update gem sass resulted into this error

    As an alternative, we attempted to use Bootstrap v3.3 using the Customize and download option. The generated configuration is saved here and can be revisited and customized further if need be. This enabled us to download customised compiled css and js bootstrap files that were used to redesign the reference app login and home pages shown below. [Repo]


a) Small Screen View

b) Medium Screen View

c) Large Screen View


a) Small Screen View

b) Medium Screen View

c) Large Screen View

As can be seen in the screenshots, adding the icons proved to be a challenge.

Also, a mock of the reference application home page was created in an OWA instance to test out Bootstrap 4. [Repo]

a) Small Screen View

b) Medium Screen View

c) Large Screen View


In order to replace the Reference Application Style Guide with Twitter Bootstrap, there is need to update gem sass to v3.3 or higher. Using Bootstrap in place of a custom OPENMRS style guide is however strongly encouraged to:

  • Achieve responsiveness,
  • Enable quick adaptability of new developers (Bootstrap is popular and hence there is no need to familiarise oneself with a whole new framework), and
  • Enjoy all associated benefits of Bootstrap’s huge support community.

cc: @dkayiwa, @ssmusoke


@nagadya Thank you for the detailed update

Did any of the more recent versions from this page https://rubygems.org/gems/sass/versions/ fail to work? @wyclif @raff @darius any ideas here?

Will review the rest in more detail

Would Twitter Bootstrap include a larger set of icons (broader than FontAwesome)? Or does this leave that issue unchanged?


cc: @ddesimone

@ball I know there is a separate issue in the pipeline https://issues.openmrs.org/browse/RA-1387 to update Font Awesome

Searching for “sass” on https://openmrs.jfrog.io/openmrs/webapp/#/home shows what is currently available in the OpenMRS maven repository. If you are unable to resolve rubygems:sass:gem:3.4.21 then you likely need to either add a different repository in your pom to search or you need to upload these as additional 3rd party jar versions to the OpenMRS maven repository. Hopefully @raff or @wyclif or @dkayiwa can advise on that.

I personally would love to be rid of anything ruby gem related from our build, so if this is an opportunity to do that and go with something like this and related packages, that could be interesting. But that is probably out of scope of what you are trying to do here :slight_smile:


1 Like

The issue was with updating the gem sass version. We run into this error when we attempted to @ssmusoke

@nagadya I see the error does this happen with all the versions in the link that I shared? How about the newer versions?

Lets try with one of the latest versions and get back to you.

@nagadya Do you have any updates on this? Also please do open pull requests with the changes that were implemented

@ssmusoke, currently I am working on REPORT-838. @dbamidele is still working on this but he has been away sick. He just resumed work today

Hi @ssmusoke.

While trying to update the rubygems sass version, I ran into this error:

[ERROR] Failed to execute goal on project referenceapplication-omod: Could not resolve dependencies for project org.openmrs.module:referenceapplication-omod:jar:2.7.0-SNAPSHOT: Failure to find rubygems:sass:gem:3.4.21 in http://mavenrepo.openmrs.org/nexus/content/repositories/public was cached in the local repository, resolution will not be reattempted until the update interval of openmrs-repo has elapsed or updates are forced -> [Help 1]

So I followed the url from the error http://mavenrepo.openmrs.org/nexus/content/repositories/public and I was able to locate rubygems>sass folder https://openmrs.jfrog.io/openmrs/public/rubygems/sass/ and I discovered they only have two versions, v3.2.5 and v3.2.10

So I changed the sass version in the pom.xml file from v3.2.5 to v3.2.10 and I ran mvn install and it installed successfully.

I then added the bootstrap scss and I clean install again and now I’m getting the same error with v3.2.5 https://pastebin.com/xk9mK2Ya.

I think an optional third party jar version like @mseaton suggested is worth giving a try.

@raff Just checking on how to get more recent versions of the sass gem from Bintray

I could deploy it to our maven repo. What version do you need and where do I get it from?

Actually, could we please compile and bundle the Bootstrap 4 OpenMRS Style Guide with webpack (in a separate project) instead of using Maven? It’s well described here https://getbootstrap.com/docs/4.0/getting-started/webpack/.

Maven is not really suited for front-end development. We will just put the generated bundle in the maven project or fetch it with https://github.com/eirslett/frontend-maven-plugin. It will be super easy to use in Open Web Apps as well.

@raff Would you be available to help with the re-architecture? it makes sense to use the best tool for the job.

What would be the path to achieve moving from sass to webpack? Will it support using Boostrap as a foundation, with stylesheets for Ref App, and custom themes to be overridden by implementors?