Kickstarting Integration of Twitter Bootstrap for Ref App UI for 2.6

Yes responsiveness was just the first value to be gotten from Boostrap but the largest benefit is to provide standard widgets for the OpenMRS UI to build upon as more sections are added without having to add more CSS.

It would be worthwhile to see how to get the dashboard integrated with Boostrap grid as a basis over the custom CSS now available

Ah okay so I’ll go ahead and implement it eitherways right?

The word I would use to describe the screenshot you shared is not “responsive,” but “unusable.” Maybe your less-than-40-Year-old eyes are more forgiving, but I would not consider 5-point font acceptable.

On a mobile platform, you should not get a miniaturized version of the app; rather, the patient header (e.g., name + identifier) preferably fixed at the top with a page scrolling beneath with each section (one at a time) stacked atop each other followed by actions (or actions & navigation accessible via a burger icon at the top left).

I agree with @burke . On a mobile device ,it tends to look kind of straining to the eyes. Bootstrap has made the grid system for this very purpose so that on making a few minor changes to the class name of elements ,we have an app suitable to be used on devices of all sizes.

@bholagabbar Any updates or progress on this POC?

I did. There are a lot of quirks working with this and I’ll try explaining what the problem is…

There is a lot of cross module referencing. Parts of the page are written in coreapps module, that references parts from the appui module. I spent some time looking here and there. I didn’t want to mess with the existing CSS and injecting divs with Bootstrap classes into Groovy Scripted pages wasn’t working out very well.

I ended up downloading a statically generated page as an HTML file and figured I could try integrating Bootstrap in there, just for a Demo. As soon as I added the Bootstrap dependencies from the CDN, a bunch of (bad) things happened

  1. The Navbar broke down and stopped resizing. This issue cannot be resolved withot modding existing CSS

  2. The text wrapped with Bootstrap classes automatically became a lot smaller. Again, possible CSS confilcts.

  3. The statically generated pages have a LOT of missing tags and. This means that somewhere in our GSPs, we haven’t closed tags right. This made the new divs malfunction and introducing the bootstrap column grids weren’t quite functioning right.

Image: The navbar won’t extend, the extremely small text is a result of adding the Bootstrap CSS file.

It just didn’t feel right. It felt like introducing something that was not needed and had no space/requirements for. There’s too much overhead and getting the existing CSS to play with this. I didn’t incorporate any Bootstrap except for responsive tags but everything broke loose as soon as I introduced the Bootstrap CSS file itself.

I feel that someone(current volunteers/GSoC 17 aspirants) can take the REST API and build a dashboard as POC utilizing Bootstrap for views and simple Ajax calls.

Again, as for the original proposition of integrating it into the current module, I wouldn’t do it, primarily due to too many styling conflicts.

One idea: if the specific goal is responsiveness then we could try adding only the grid portion of bootstrap’s CSS to our own uicommons. (This thread implies we can just import these into the existing SASS build process of uicommons’s CSS.)

Since I’m very familiar with how the current style guide is built, I also took a stab at incorporating bootstrap onto this screen.

Executive Summary

  • It’s not too painful to do
  • The actual process involves swapping classes from the uicommons style guide for classes from bootstrap.

If we were to do this for the entire refapp, we have to do one of:

  • (a) keep both bootstrap and uicommons, which is bloated, and likely to have conflicts
  • (b) remove the uicommons styling from the distro, and change all refapp (and PIH, and Mekom, etc) modules to use bootstrap classes, which is a lot of work, and maybe not feasible across all these groups
  • (c) leverage bootstrap-sass and rewrite the existing uicommons styles to use bootstrap’s mixins. This requires actual thinking, whereas the other two options are pretty brute-force.
  • (d) do things on a page-by-page basis, e.g. new pages and pages that we fully refactor can use bootstrap natively, but take an approach like (c) for existing pages

Details of what I did:

Open a patient summary on in Chrome and do Inspect Element. Then…

  1. On body disable the max-width:1000px rule (have to do this twice because our CSS seems to be duplicated)
  • this one change actually allows the entire UI to correctly stretch to larger window sizes. (I can’t believe we never tried this before. @mogoodrich, @mseaton FYI )
  1. Add bootstrap (from a CDN at the top of the <head>
  • this actually breaks some of the good effect from the previous change
  1. Find <div id="content" class="container"> and change the class to container-fluid.
  • this fixes the patient header, but not the content
  1. Find the next <div class="container"> and change the class to row.
  • we’re back to where we started without bootstrap (i.e. it correctly scales bigger)
  • now, to handle scaling down…
  1. Find the two instances of <div class="info-container column"> that represent the two columns and replace the class with col-md-5 col-sm-6 col-xs-12
  2. Find the <div class="action-container column"> and replace the class with col-md-2 col-xs-12
  • FYI this means that:
    • md: on normal displays all 3 will be next to each other with relative sizes 5/5/2
    • sm: on tablet-sized, the two columns will fill the container with equal relative sizes of 6/6
    • xs: on mobile-sized, each column is full-width (12) hence stacked.

This actually worked pretty well!

Here is the very wide screen:

Here is virtual ipad:

And here is a tiny window size:

(on Chrome’s virtual iphone it actually looks the same as on a tablet; I don’t know why)


@darius Thank you for taking the time to look into this. The responsiveness is the first win from using Twitter bootstrap and I am comfortable with following option c for ui-commons with the aim of replacing the style guide with Boostrap completely the version after Ref App 2.7 (October 2017) release.

Option d with new page will need to follow the Boostrap style while old pages are migrated as needed provides a prgamatic migration path for the Ref App

Any other thoughts on approach?

The big next step will be to some components in play, leveraging the work to be done on and

@darius is it possible to sneak in the css for the components and their JS while you wrap up the POC?

@ssmusoke that was my POC and it’s done. I just had a bit of time while I was replying to Shreyans.

Please give some examples of which components you’re you’re looking to get from bootstrap. Adding a requirement on jquery for future work sounds like a bad idea to me. I would want the reference application to be moving towards newer technologies, not older ones.

Looking at bootstrap’s list of components, we already support a lot of this in uicommons.

We have equivalents for: glyphicons, dropdowns, button groups, tabs, breadcrumbs, labels, badges, page header, alerts, panels.

We don’t have: button dropdowns, input groups, tabs-with-dropdowns, navbar (but we already have a header), pagination, jumbotron, thumbnails, progress bars, media object, list group, responsive embed, wells.

Most of these things we don’t have in uicommons don’t seem very OpenMRS-relevant to me. (And some of them are probably trivial to implement in the existing uicommons.)

I haven’t been following this thread 100%, and unfortunately I’m not much of an expert in css styling in general. None of us here at PIH are–generally it was the Thoughworks team working with us a few years ago that set up the initial styling (and our PIH styling that interacts with it).

So I am somewhat worried about a solution Darius mentions like “(b) remove the uicommons styling from the distro, and change all refapp (and PIH, and Mekom, etc) modules to use bootstrap classes, which is a lot of work, and maybe not feasible across all these groups”.

That being said, I don’t want to be too much of a barrier to progress, and, of course, we might want to take advantage of the styling improvements ourselves… we aren’t 100% in love with the current style.

But, again, it’s hard for me to comment too intelligently or understand the amount of work needed if we do such a migration.

Once we get closer, would it be possible to make a spike of the potential changes in a branch of UI commons? I’d be willing to temporarily pull in into the PIH EMR distro to get a better understand of the ramifications, and the potential work to fix.

Take care, Mark

@darius my understanding is that the purpose of Boostrap is to move the core infrastructure from uicommons (which is OpenMRS maintained) to a more widely used toolkit that web developers from other walks of life can help and for the dev team to focus less on keeping the low level plumbing maintaining css/html.

Now that Ref App is looking to add configurable dashboards as well as widgets for the Patient and Clinician facing dashboards, with React/Angular and other UI frameworks, there needs to be a standard to what the well formed HTML will look like, so there will be more non-OpenMRS relevant widgets.

If that’s the goal, then let’s stop calling it just “integrate bootstrap” and start calling it “replace existing style guide with a new one based on Bootstrap”.

So, with that as the vision, we should lay out a plan to get there incrementally. I suggest scheduling a design call for us to start planning this.

I agree with you @darius on this one

Hey @darius! @bholagabbar mentioned that you guys were looking for an UI/UX developer and designer. Going through this thread I found mentioned requirements are something I find myself fit for. We can get on a dev call and understand the requirements better. My GitHub : LinkedIn:

1 Like

@nashvail A pleasure to e-meet you, will see what I can organize as soon as I can find a slot, hopefully next week

likewise Stephen! Next week sounds perfect.

@dkayiwa Here is the talk thread with a spike done by @darius for Bootstrap integration