Upgrading from the jharesponsive Package

If you’re upgrading an Angular application that uses the Angular components (i.e. you previously imported the jharesponsive package), there is a one-time set of upgrade steps that you must perform in order to adopt this release.

These upgrade steps primarily involve the package.json, .npmrc, angular.json, app.module.ts, and app.component.html files.

Before getting started

• Your application must be upgraded to the 2023.0.0 release before beginning this upgrade.
• If anything looks incorrect to you after the upgrade, please first check your HTML and verify that you’re using the correct tag names, property names, and property values.
  • In our guided upgrades we encountered one app that was using incorrect property values that just happened to work in the past, but which no longer continued to work after the upgrade (which is not unexpected).
• If your app uses the internal HTML+CSS for any component instead of the component API, that will break with this upgrade. Your app should be using the components directly. Component internals are private and are subject to change from release to release.
  • In our guided upgrades we encountered one app that was using internal HTML and CSS in the nav bar rather than the components. Their nav bar only looked correct after they switched to using the actual components.
• If your app uses global CSS to override any of the enterprise CSS, that will no longer work since web components use an approach called shadow DOM, where all CSS is embedded within each component and is not able to be overriden.
  • While the practice of overriding the RUI CSS has never been supported in the past as it was a brittle practice that could undermine consistency), the open theming with CSS variables support will allow you to override the default CSS values in a safe way going forward.
• If your app uses Bootstrap CSS, you can continue to do so, but be aware that Responsive UI no longer themes the Bootstrap CSS.
  • Responsive UI originally “paved over” the Bootstrap CSS, but we’ve been moving away from Bootstrap over the last 8 years and are fully removing it as of the 8.0 release.
  • In our guided upgrades we encountered one app that was using button elements with the Bootstrap btn and btn-primary CSS classes applied. Those buttons will look incorrect until they are converted to use the jha-button component instead.
• If your app is still using the deprecated jhaButtonListType property in jha-dialog-box and jha-question, those must be converted to dialog box buttons.
  • In our guided upgrades we encountered one app that was still using the deprecated jhaButtonListType property, so their dialog box buttons will remain missing until they replace that property with jha-dialog-box-button component instances.
• The expand-on-hover support that was previously in the Angular jha-nav component was omitted when we built the rui-nav web component, so that functionality is no longer part of the Angular support, since jha-nav now wraps rui-nav.

.npmrc

• Add the following to your .npmrc file to define the @jkhy scope. If your application has a local .npmrc file, make this change in there. Otherwise make this change to the global .npmrc file in the user folder for your operating system.

@jkhy:registry=https://jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/registry/
always-auth=true

• You should keep the existing @jha scope in this file if you will still need to install the older jharesponsive package in other repos.
• Your existing personal access token (PAT) will work with this new scope.

package.json

Responsive UI deploys new package names as of release 8.0, so you must update the package name in package.json in addition to updating the version number.

• Replace "@jha/jharesponsive": "x.y.z" with "@jkhy/responsive-ui-angular": "9.2.0" in the package dependencies section.
• Add "@jkhy/responsive-ui-wc": "9.2.0" to the package dependencies section.

angular.json

• Remove any @jha/jharesponsive/*/*.min.css CSS imports in angular.json styles section(s). This is replaced with the new CSS in the next step.
• Add new CSS imports to the styles section(s):

"node_modules/@jkhy/responsive-ui-wc/styles/rui-animation.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-app.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-dashboard.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-drag-and-drop.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-fixed-layout.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-fonts.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-form.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-global.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-icon.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-match-height.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-native-html.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-popup-notification.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-responsive-layout.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-responsive-table.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-slider.css",
"node_modules/@jkhy/responsive-ui-ag-grid/rui-third-party-ag-grid.css",
"node_modules/@jkhy/responsive-ui-angular-split/rui-third-party-angular-split.css",
"node_modules/@jkhy/responsive-ui-jodit/rui-third-party-jodit.css",
"node_modules/@jkhy/responsive-ui-ngx-bootstrap/rui-third-party-ngx-bootstrap.css",
"node_modules/@jkhy/responsive-ui-prime-ng/rui-third-party-prime-ng.css",
"node_modules/@jkhy/responsive-ui-wc/styles/rui-wizard.css",
"node_modules/@jkhy/responsive-ui-wc/themes/rui-theme-pacific.css"

• Update the assets section to copy the new theming files to the correct location:

{
    "glob": "rui-theme-*.css",
    "input": "node_modules/@jkhy/responsive-ui-wc/themes",
    "output": "./assets/rui-themes"
}

• If your app doesn’t specifically use Bootstrap CSS, you can remove "node_modules/bootstrap/dist/css/bootstrap.min.css" from angular.json if it’s there. Bootstrap is no longer required.
  • If your application is still using any old Bootstrap CSS, you can continue to leave the Bootstrap CSS in place. NOTE that with Bootstrap no longer being a dependency of the Responsive UI, it will not get installed automatically. If you are still using Bootstrap, ensure that it is included in your applications package.json.
  • IMPORTANT: If you keep the Bootstrap CSS in your application, you must remove rui-responsive-layout.css from angular.json as the two will conflict with each other.
  • Be aware that Responsive UI no longer overrides the Bootstrap CSS, so if you choose to continue using Bootstrap, you’ll see the native Bootstrap appearance.
• Remove "node_modules/noty/js/noty/packaged/jquery.noty.packaged.min.js" from angular.json if it’s there. Noty is no longer required.
• Remove "node_modules/jquery-sparkline/jquery.sparkline.min.js" from angular.json if it’s there. jQuery sparkline is no longer required.

Other code

• Do a mass replace of all instances of @jha/jharesponsive with @jkhy/responsive-ui-angular throughout your application.
  • This will update any view-level TypeScript that imported Responsive UI Javascript to use the new package.
  • If your code is in a monorepo with multiple projects and you’re only upgrading one of those projects, you’ll want to be careful to scope the search/replace to only the project(s) that you want to upgrade.
• If your application references any of the Responsive UI CSS variables, you will need to add an rui prefix to each of these references.
  • You can tell if your app is referencing CSS variables by doing a search for var(-- in your app’s code. If you don’t find any matches, then there’s nothing more to do here.
  • Each CSS variable now has a rui prefix that acts as a namespace.
  • For example, if you previously referenced the --line CSS variable using var(--line), you would change that to var(--rui-line).
  • If your application is only referencing CSS variables from Responsive UI, you can do a mass replace to replace var(-- with var(--rui-.

src/app/app.module.ts

• Add imports for all Responsive UI web components:

import '@jkhy/responsive-ui-wc/components/rui-buttons/rui-buttons-imports';
import '@jkhy/responsive-ui-wc/components/rui-data-pager/rui-data-pager-imports';
import '@jkhy/responsive-ui-wc/components/rui-dialog-box/rui-dialog-box-imports';
import '@jkhy/responsive-ui-wc/components/rui-header/rui-header-imports';
import '@jkhy/responsive-ui-wc/components/rui-icon/rui-icon-imports';
import '@jkhy/responsive-ui-wc/components/rui-input/rui-input-imports';
import '@jkhy/responsive-ui-wc/components/rui-layout/rui-layout-imports';
import '@jkhy/responsive-ui-wc/components/rui-mega-menu/rui-mega-menu-imports';
import '@jkhy/responsive-ui-wc/components/rui-master-detail/rui-master-detail-imports';
import '@jkhy/responsive-ui-wc/components/rui-nav/rui-nav-imports';
import '@jkhy/responsive-ui-wc/components/rui-notifications/rui-notifications-imports';
import '@jkhy/responsive-ui-wc/components/rui-password-strength-meter/rui-password-strength-meter-imports';
import '@jkhy/responsive-ui-wc/components/rui-percentage-circle/rui-percentage-circle-imports';
import '@jkhy/responsive-ui-wc/components/rui-progress-bar/rui-progress-bar-imports';
import '@jkhy/responsive-ui-wc/components/rui-process-timeline/rui-process-timeline-imports';
import '@jkhy/responsive-ui-wc/components/rui-rating/rui-rating-imports';
import '@jkhy/responsive-ui-wc/components/rui-record-detail/rui-record-detail-imports';
import '@jkhy/responsive-ui-wc/components/rui-session-timeout/rui-session-timeout-imports';
import '@jkhy/responsive-ui-wc/components/rui-tabs/rui-tabs-imports';
import '@jkhy/responsive-ui-wc/components/rui-tile/rui-tile-imports';
import '@jkhy/responsive-ui-wc/components/rui-tooltip/rui-tooltip-imports';

• Remove import * as bootstrap from 'bootstrap'; from app.module.ts unless you are depending on this for your application. The Responsive UI no longer requires Bootstrap.

src/app/app.component.html

• Replace the jha-main-header CSS class on your header element with the rui-app-header CSS class. This is critical for app layout.
• Replace the jha-main-nav CSS class on your nav element with the rui-app-nav CSS class. This is critical for app layout. If there is a jha-main-nav ID on this element, it can be removed.
• Remove jha-unsaved-changes-dialog-box from app.component.html if it’s there. This component is now embedded within the jha-app component.
• The jhaAppearance and jhaDisableAnimations properties that were previously deprecated have now been removed. Remove these as attributes on the jha-app component.

Build and test your app

• Change directory into your application’s main directory.
• Delete the .angular folder to avoid Angular caching.
• Delete the node_modules folder.
• Delete the package-lock.json file.
• Run npm install to install package dependencies.
  • The new package has a dependency on lodash that will result in a CommonJS warning. You can suppress this warning by adding it to the allowedCommonJsDependencies section of your angular.json file.
• Build and examine your application using your normal processes.
• Contact us with any questions.

Clean up

Once your application has been upgraded to 8.0 and looks good, you can now attempt to remove some of the third party frameworks that are no longer needed in Responsive UI. Removing these frameworks isn’t critical, but it can reduce your application’s download size and dependency complexity.

After each and every step below, be sure to repeat all of the steps in the Build and test your app section above after each removal.

Any one of these removals could break your app if you have unknown dependencies on any of them, so be sure to make the following changes one at a time, with a full build and test after each step.

If any of the removals below cause your application to break, reverse that one removal and keep that dependency in your app. You can then move down the list

src/app/app.module.ts

• Remove import * as $ from 'jquery'; from app.module.ts if it’s there.

angular.json

• If your app doesn’t specifically use jQuery, you can remove "node_modules/jquery/dist/jquery.min.js" from angular.json if it’s there. jQuery is no longer required.
  • If your application is directly using jQuery, you can continue to use it. It’s just no longer required.

package.json

• You can remove the jquery and jquery-sparkline packages from package.json as these are no longer required.