@jha Package Setup and Upgrade Information

First-timers: Getting set up for Responsive UI

Prerequisites

• Ensure you have Node.js v14.15+ installed.
  • If you don’t have Node installed on your machine, download the LTS version at https://nodejs.org/en/download/.
  • You can check your current version by opening a command prompt and executing node -v.
• Ensure you have npm v6.14+ installed.
  • You can check your current version by opening a command prompt and executing npm -v.
  • NPM comes with Node.js. If you have an older version, open a command prompt and execute npm i npm@latest -g.
• If your project will use the @jha/jharesponsive or @jha/rui-angular packages, ensure you have Angular CLI installed globally, matching the version that’s currently being used in the @jha packages. You can check the version number on the Compare Framework Versions page.
  • You can install Angular CLI by opening a command prompt and executing npm i -g @angular/cli.
  • If you already have an older version of Angular CLI installed globally, you will need to first delete that before installing the latest. You can uninstall the global Angular CLI by opening a command prompt and executing npm uninstall -g @angular/cli.

Create @jha registry for local development

The @jha family of frameworks (including jharesponsive, rui-angular and rui-wc) reside in an Azure DevOps Artifact.

If you’re creating a Responsive UI application for the first time, you will need to add a new registry with the @jha scope.

1. Log into Azure DevOps - https://jackhenry.visualstudio.com.
2. If you’re not already a member of the JHA Responsive Controls project, request access by sending an email to responsiveui@jackhenry.com.

3. Next, open your user .npmrc file.

   • On Windows, this file will be at C:\Users\[username]\.
   • On a Mac, the location will be Macintosh HD\Users\[username].
   • If one is not there, create an empty .npmrc file and save it to this folder. See how to create a file without a filename in Windows.

4. Inside the .npmrc file, copy and paste the content below. Save the file.

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

; begin auth token
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/registry/:username=JackHenry
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/registry/:email=npm requires email to be set but doesn't use the value  
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/:username=JackHenry
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/:email=npm requires email to be set but doesn't use the value
; end auth token

5. Navigate to your Personal Access Tokens within Azure DevOps User Settings.

6. Click on New Token. Enter a Name, select JackHenry for the Organization and set an Expiration, up to 1 year.

   • Select Custom defined for Scopes. Then scroll down to Packaging and check Read.
   • Press the Create button.

7. With the token successfully generated, leave this window open.

8. The personal access token created in the previous step needs to be Base64 encoded.

• From a command/shell prompt execute:

node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"  

• After execution, you will receive a PAT> prompt.

• Go back to the Azure DevOps PAT window and copy the token to the clipboard.
• Paste your personal access token value into the PAT> command prompt and press Enter.
• Copy the response Base64 encoded value.

9. Replace both [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] values in your user .npmrc file with the Base64 encoded personal access token created in the previous step.

10. Once these steps are complete, you should be able to install the latest jharesponsive, rui-angular and rui-wc packages into your local project by adding it to your package.json or running an npm install on @jha/jharesponsive, @jha/rui-angular, or @jha/rui-wc.

Using the Responsive UI components

To begin using Responsive UI, start by downloading either the starter template or the sample app:

• The starter template is a simple, two-page application that sets up a starting point for a new Responsive UI application. It shows simple examples of basic page setup, routing and theming, but does not include examples of the majority of our patterns.

• The sample app is an example of a ‘kitchen sink’ app. It includes working examples of each Responsive UI pattern.

To use either of these apps, download them from the Current Release page and follow the steps below.

• Unzip the application on your hard drive.
• Open a command prompt and change directory to the root of your application.
• Execute npm install at a command prompt to install all of the required dependencies.
• Once the installation is complete, execute ng serve at a command prompt to build the application and start the local server.
• Open your application in a browser at http://localhost:4200
• For additional information on how to use Angular CLI and Responsive UI, view the Angular CLI documentation on GitHub.

Using Responsive UI in an Azure pipeline

There are two ways to use the Responsive UI Controls in an Azure Pipeline.

1. One option is to create a feed that pulls in the Responsive Controls Azure Artifact as an upstream source. The benefit of this approach is that a PAT (Personal Access Token) is not required so there is no concern of needing to renew an expiring PAT once a year. The downside is that this approach has been reported by some groups as being unreliable. Many groups have used this approach without fail for a long period of time, but some groups with more complex setups have started to get authentication errors with no changes to setup or the pipelines.

2. Another option is to create a new Service Connection with an Authentication Token (PAT). This approach requires the PAT to be renewed upon expiration, but has proved to be a more reliable method of access.

Creating a feed for an Azure DevOps project

If you have an Azure DevOps project, you can use the JHA Responsive Controls package as an upstream source and install it during an automated Pipeline build.

1. If you don’t already have an existing feed setup for your project, create a new feed within Artifacts in your project. Give the feed a Name, and leave the defaults selected for Visibility, Upstream sources, and Scope.

2. Once the feed has been created, click the gear icon on the right to update the feed settings.

3. Next, click Upstream sources followed by Add upstream source.

4. The next step can vary depending on your Azure organization. At https://dev.azure.com, the organizations you belong to are listed on the left.

The JHAResponsiveControlsPackage is in the JackHenry organization.

• If your project is also in the JackHenry organization, select Azure Artifacts feed in this organization.
• If your project is outside of the JackHenry organization, select Azure Artifacts feed in another organization.

If your project is in the JackHenry organization, select the JHAResponsiveControlsPackage from the Feed dropdown. Then select npm for the Package type(s) and update the Upstream source name if you would like to customize it. Then press the Add button.

If your project is outside of the JackHenry organization, enter azure-feed://JackHenry/JHAResponsiveControlsPackage@Local for the Azure Artifacts feed locator. Then select npm for the Package type(s) and update the Upstream source name if you would like to customize it. Then press the Add button.

Once complete, you should be able to install the @jha/jharesponsive package during a pipeline build. Within the npm install task, expand Custom registries and authentication and select Registry I select here. Then select your feed from the dropdown.

For more information on setting up feeds and upstream sources, view Microsoft’s documentation on configuring upstream sources.

Creating a service connection for an Azure DevOps project

1. To create a new Service Connection, go to the Service Connection page within the Pipelines section of your Azure Project Settings. Press the Create service connection button.

2. Select npm for the connection type, then click next.

3. Enter the following values in the New npm service connection form:

• Select the Authentication Token method.

• Enter https://jackhenry.pkgs.visualstudio.com/_packaging/JHAResponsiveControlsPackage/npm/registry/ for the Registry URL.

• For the Personal Access Token, create a new PAT within your User Settings, but ensure that you’re in the JackHenry organization. Paste that PAT in the Personal Access Token input. Do not base64-encode the PAT like you would when pasting a PAT into an .npmrc file.

• Give the service connection a name.

• Check the Grant access permissions to all pipelines checkbox.

• Press the Save button.

4. In your pipeline npm install step, expand the Custom registries and authentication section. Select the Registry I select here option and select your newly created service connection.

Upgrading to a new version of Responsive UI

• Open the package.json file in the root of your application.
• Update the version number for the @jha/jharesponsive package to point to the latest version number, which is 2023.0.0 for this release.
• Check the Compare Framework Versions page to see if you need to update other dependency and devDependency packages. Incompatible package versions can lead to build and styling issues.
• Delete the node_modules folder and package-lock.json file in your application root.
• Open a command prompt, change directory to the root of your application, and install all dependencies with npm install.
• Reference the current release notes to see information on breaking and non-breaking changes.