Migrating from Semantic UI to Bootstrap

This is a guide to porting Angular applications from Semantic UI to Bootstrap, following the ALMA UI Guidelines.

Getting started

Development environment

You'll be changing the front-end a lot, barely touching the back-end, if at all. Make sure you configure the front-end such that it can be launched with npm install; ng serve -o on port 4200 while the back-end runs on its customary port, typically around 10000.

In the case of the DRA Tool, for instance, that requires setting developmentMode = true in app.globals.ts, which has the effect of changing resourceServerURL from /dra-tool to http://localhost:10000/dra-tool.

Note Remember to undo this setting when you're done!

On the back-end side you'll need a CORS filter that maps the value of the Origin request header to the Access-Control-Allow-Origin response header; plus assorted other settings.
See OBOPS/dra-tool/src/main/java/alma/obops/dratool/security/SimpleCORSFilter.java for an example.

Note This may conflict with the @CrossOrigin annotation of the controller classes/methods, causing duplicated requests: make sure the filter is disabled when you're done! (Comment out the @Component annotation on the CORS filter.)

ALMA UI Guidelines

See the Getting Started section of the ALMA UI Guidelines documentation for a description of how to set up Bootstrap, ALMA styles, fonts and icons.

Installing NG Bootstrap

NG Boostrap is a library allowing Bootstrap to be integrated with Angular applications.

To install it:

• Add "@ng-bootstrap/ng-bootstrap": "<version>" to the dependencies field of package.json, where version is ^5.1.5 for Angular 8.x.x
  NOTE See here for the version numbers.

• In app.module.ts:
  import {NgbModule, NgbActiveModal} from '@ng-bootstrap/ng-bootstrap'
  then add NgbModule and NgbActiveModal to the imports and providers arrays, respectively:

    imports: [ ... NgbModule ... ],
    providers: [ ... NgbActiveModal ... ],

Containers

SUI containers need to be changed to their Bootstrap equivalents. See Migrating Containers from Semantic UI for more info.

Migrating ng2-semantic-ui components to ng-bootstrap

Library ng2-semantic-ui is the counterpart of ng-bootstrap for Semantic UI. Components written with the former must be rewritten to take advantage of the Angular/Bootstrap integration facilities.

Backwards compatibility

To ease the migration, a CSS compatibility layer allows you to leave many SUI classes in place.

Buttons

For <button> elements:

• SUI classes almacolor and red map to btn-primary and btn-danger, respectively
• SUI classes ui tiny compact button map to Bootstrap btn btn-sm

Checkbox

See Migrating Checkboxes from Semantic UI.

Datepicker

See Migrating Datepicker from Semantic UI.

Dropdown

See Migrating Dropdown from Semantic UI.

Header bar

See Migrating the Header Bar from Semantic UI.

Icons

See Migrating Icons from Semantic UI.

Modals

See Migrating Modals from Semantic UI.

Popups

See Migrating Popups from Semantic UI.

Select

See Migrating Selects from Semantic UI.

Tabset

See Migrating Tabsets from Semantic UI.

Tables

Replace SUI table definitions
<table class="ui basic table"> ... </table>
with the equivalent Bootstrap idiom
<table class="table table-bordered"> ... </table>

If the table has the selectable class, add table-hover in the bootstrap version.

Final clean-up

Some steps below may not apply to your application.

• Remove ng2-semantic-ui from package.json
• Remove any links to the Semantic UI stylesheet from index.html
• Remove any references of SuiModule from app.module.ts
• Remove unneeded style definitions from styles.css
• Remove unneeded font files (esp. FontAwesome) from src/main/angular/src/assets/fonts