ldx-home-plate

Initial setup

This document will serve as a basic guide to getting started with the ldx-home-plate repo

1. Install Node Version Manager (nvm)

Run the nvm install script. The latest version can be found here.

2. Install Node versions

Once the nvm install script is completed, you can now install various versions of Node. Start by doing nvm install 10.15.0 and then nvm install 11.6.0. Nvm will allow you to hot-switch between Node versions when required. If you have previously installed Node by other means (such as Homebrew), you may need to uninstall that implementation before installing it with nvm.

3. Install Yarn

Yarn is a tool to manage and install dependencies through npm. Installation instructions here: https://yarnpkg.com/en/docs/install#mac-stable https://yarnpkg.com/en/docs/install#alternatives-stable

4. Update your .bash_profile

Find your bash profile at ~/.bash_profile. This is a hidden file. Open it in a text editor and add the following line: export NODE_ENV=development. You may have to restart your computer for this to take effect. To make it work before a restart, type that same line in the terminal to set the environment variable. This will tell Node that you are in development mode, enabling development-only features such as the proxy target menu.

5. Clone the repo from the remote

Switch to the folder that you want your code to live, e.g. cd ~/Documents/ldx-home-plate. If the ldx-home-plate directory doesn't exist, create it first. Next, use this command to copy down the repo: git clone [email protected]:tmfi/ldx-home-plate.git

6. Install repo dependencies

Install the repo's dependencies by running the yarn command from the root of the project directory. Note: you may need to install additional dependencies globally using the -g flag, e.g.: yarn install gulp -g

7. Useful commands when developing

Use the command npm start to start the app in dev mode with credential autofilling and hot module replacement enabled. Use the npm run for:IE to start the app for testing in IE 11. This remove some development features in favor of IE 11 compatibility. Use the npm test command to get the server running and run unit tests on every change. Use the npm run cypress command to start the UI automation tests Use the npm run for:UITests to start the app for UI automation test deveopment. This will turn credential autofilling off, which can cause issues for the automation tests.

Logging into the App

Logging into the app involves a two-step process:

1. Autofilling your logins and passwords

Within the project folder, create the file /DevCreds.json. The file should be a valid json object where the keys correspond to environment names in `server/proxy/proxy_targets.ts...

{
  "Lotus": [
    [
      "lotusUsername1",
      "lotusPass1"
    ],
    [
      "lotusUsername2",
      "lotusPass2"
    ],
    ...
  ],
  "Austin": [
    [
      "austinUsername1",
      "austinPass1"
    ],
    [
      "austinUsername2",
      "austinPass2"
    ],
    ...
  ]
}

When an environment is selected from the proxy target menu (see below), it will expand to show the associated credentials. NOTE: /DevCreds.json is purposely untracked by GIT. So please do not attempt to commit this (or any other) file containing secrets to the project.

2. Proxy target menu

You can choose the targeted environment from the app's main login screen using the proxy target dropdown. Select the preferred environment to immediately re-direct Node to that environment. You can now click "Login" to attempt a connection to the targeted server. New root level API paths will need to be manually added to the list of proxy paths used by node to decide which request should be redirected to the remote server. This list can be found and modified in /server/proxy/proxy_paths.ts.

Adding strings visible in the UI

All strings visible to users of the application must be run through a translation method. For convenience this method has been added to the global scope at window.t. All strings should be fed to the t method, eg t 'My new string'. Doing so will automatically add the new string to a strings file (/src/app/strings/en-US.json), where it can easily be translated later. /src/app/strings/en-US.json changes should be committed to the project along with the rest of your changes.

Note: The verify-translations script searches through the raw, uncompiled .ts(x) files. Passing variables directly into the t() method will not be captured by the script, because the variables cannot be resolved by searching through what is essentially plain text.

To ensure that strings are properly added to the locale file, use string literals inside the t() method, instead of variables:

DO THIS:

messageText = if messages.length > 1 then t("You have new messages") else t("You have a new message")

...NOT THIS:

messageText = if messages.length > 1 then "You have new messages" else "You have a new message"

t(messageText)

A form of string interpolation is available when variables need to be inserted in translated text by wrapping segments in double underscores (__).

t('Hello __fullName__', {fullName: 'John Smith'})