Skip to main content

Upgrading from PMACS Bootstrap to the new PMACS Frontend

Checklist

  • Change Gem from pmacs-bootstrap to pmacs-frontend
    • Ensure that pmacs-frontend is listed after pmacs_app_resources in the Gemfile so that the error partials of pmacs-frontend take precedence.
  • Change pmacs-bootstrap references to pmacs-frontend in asset manifests:
    • application.scss
    • application.js
  • Delete Old Layout Files
    • application.html.erb
    • devise.html.erb
    • error.html.erb
  • Precompile on_ready assets
    • Even if you decide not to use this feature, you must create an empty app/assets/javascripts/on_ready.js file
    • Optional: Transfer $(document).ready code to a app/assets/javascripts/on_ready directory for end-of-DOM inclusion
    • Be wary that you'll still need to prefix some handlers with events, such as $('turbolinks:load')
  • Use Hooks to set up things like the App Navigation, the Application Title, and the HTML <title> tag. The old Gem would let you set a lot of this directly in the layouts that you copied into each project. Hooks offer replacement configuration.
  • Remove pmacs-javascript and address JS deprecation, if applicable
  • Upgrade individual Bootstrap 3 components and class-names to Bootstrap 4 equivalents. See migrating From Bootstrap 3 to 4
    • Note that PMACS Bootstrap used Bootstrap 3 but cherry-picked some Bootstrap 4 components, such as cards.
  • Upgrade from Poltergeist to Selenium for testing JS functionality. Refer to our Rails Skeleton for the latest compatible setup for CI.
  • If you have any glyphicons hanging around from CUI 3, now is the time to ditch them. Jump in feet-first to the beautiful world of FontAwesome 5!

Once this is complete, you will need to click through all of your UIs and make sure everything looks good! It won't at first, but you can make it so!

Delete Old Layout Files

In PMACS Bootstrap, applications would wire up the page chrome by calling render 'bootstrap/layout' in the /app/views/layouts/application.html.erb file. Now, with PMACS Frontend, your application doesn't need an application layout file at all! The following layouts are included (and rendered) in Frontend, so delete them from your application:

  • application.html.erb
    • The first step to upgrading is to delete your application.html.erb layout file altogether (as the gem supplies the layout). Your application simply uses the layout hooks as described above.
  • devise.html.erb
    • PMACS Frontend now provides a default Devise layout, eliminating the need for every project to have a duplicate. If you have a devise.html file you should delete it.
  • error.html.erb
    • Additionally, if you specified an error file to handle Devise errors, you should delete that as well.

See the Devise Views page for more information.

Check for usage of removed Javascript Gem

The Frontend is not bundled with pmacs-javascript and does not contain most of the custom JS that came packaged in PMACS Bootstrap. For a complete list of deprecated functionality, see the PMACS Javascript repository and PMACS Bootstrap assets.

The following list of functionality, while not exhaustive, is now excluded from the Frontend by default:

  • Bootstrap Dialog Alert override: with pmacs-javascript, elements with data-confirm would trigger a modal instead of a raw browser alert confirmation
    • If you are using data-confirm, it is vital that you ensure that you are not manually including pmacs-javascript, as this could silently break the data-confirm functionality. Frontend offers a complete replacement for this with no changes to the API.
  • FileInputDecoration — automatically change a naked <input type='file'> into a bootstrap button. For file inputs that are part of longer forms, we recommend starting with Bootstrap 4's file input. If you want to roll that up into something custom, you can use Stimulus, like in this example of a file-upload form bundled into a button.
  • SetActiveNav — highlight the active nav element on the sidebar. This is handled automatically by Frontend.
  • Hidden table headers—automatically hide empty tables if they had a hide-headers class. You can implement this in your project with a minimal Stimulus controller.

Upgrade From Poltergeist To Webdrivers/Selenium

Apps using Poltergeist may need to add a polyfill to allow for execution of ES6 (which Frontend uses) in tests. Better still, take this time upgrade away from the long-dead Poltergeist project and start using Selenium. Please refer to the Rails Skeleton for the current setup, which uses the webdrivers gem to manage Selenium and connect it to Capybara for tests.