Forgerock UI

Forgerock UI

Monorepo containing various Forgerock UIs.
Explore ForgeRock docs »

The purpose of this readme is to help users explore the ForgeRock UI monorepo. Which contains a variety of UI parts such as views, styles and components utilized for different ForgeRock UIs.

Quick start
Build Tools
Testing tools
Application tools
Code Style
Translations and Text
Deployment
Theming
Build command summary
Browser support

Development Quick start

Download and install the latest node or verify your node version node -v
Make sure you have yarn installed
Clone or download the repo
Navigate to newly cloned platform-ui directory, and install dependencies with yarn command: yarn install. Since this project uses Yarn workspaces, this will install package requirements in all project folders under packages
To start the development server, navigate to target project by changing directory to specific package inside the platform-ui/packages directory, and enter the command: yarn dev

Build Tools

Node - Used for deploymenet and development
Vue CLI - Vue project and distribution management (layers ontop of webpack)
Webpack - Core distribution management
Yarn - Package manager

Testing

Unit tests

Testing is achieved with the Jest Testing Framework and configured globally inside: jest.config.base.js and locally to each project inside: jest.config.js

To run unit tests across all workspaces, in the root platform-ui directory, run the command: yarn unit or yarn unit:watch
To run unit tests on a specific workspace, cd to the specific directory, and run command yarn unit

End to End tests (E2E)

Cypress is leveraged for all End to End tests

To run E2E tests, cd to the specific directory where you want to run the tests, and run e2e, or e2e:open
By default, the E2E test suite is configured to run against a UI hosted at https://default.iam.example.com, which is part of a full platform deployment. However, the tests may also be run against a remote platform or Forgerock Identity cloud deploymeny using the tasks e2e:remote or e2e:remote:open.

Testing tools

The following testing tools are installed when you install the project dependencies:

Jest - Unit testing
Cypress - E2E testing
Vue Test Utils - Vue utility testing library

Application tools

The following application tools are installed when you install the project dependencies:

Vue - Primary JavaScript framework for the project
Vue Router - Application routing Vue library
Vue Bootstrap - Bootstrap 4 Vue components
Axios - JavaScript Promise Library
Vue i18n - Translation library for Vue
Vee Validate - Form validation for Vue
lodash - Util library for preforming various efficient calculations
VueX - State management

Code style

Vue Specific Eslint Rules - Linter rules specific to Vue
General Javascript Styles - Javascript base eslint rules
CSS Lint Rules - CSS base lint rules using amalgamation of airbnb's, Googles, Idiomatic's, and @mdo's style config

Translations and Text

Application translation uses Vue i18n and the openidm/info/uiconfig endpoint to get the current user's browser language.

The project only contains en based translations and falls back to en if an unsupported language is detected. To change the default language fallback adjust VueI18n /src/main.js.

Adding and changing an existing message for the en base language involves either adding a key or editing an existing key. Keys follow JSON structure; for example, if you wanted to edit the navigation bar Profile to User Profile you would need to locate the appropriate key en.pages.app.profile and change the text. Inside of your Vue application you would then make use of that key with the built in translation function {{$t('pages.app.profile')}} or this.$t('pages.app.profile').

Adding a new translation language means creating a new translation file inside of locales folder with a key matching the translation language code.

For example:

en.json
fr.json
gr.json

Then creating a JSON key structure that should be mirrored across all of the language files.

For example:

    {
        dashboard: {
            welcomeMessage: 'Welcome!'
        }
    }

Deployment

Running yarn build creates a distribution file in the dist folder of that specific project. Each deployment use case is different.

Theming

The following theming tools are installed when you install the project dependencies:

SCSS - CSS enhancement library
Bootstrap 4 - CSS Styling framework

Theming makes use of two concepts:

Theming follows the basic Bootstrap theming guidelines and relies on SCSS variable overrides.
The theme file is loaded with an optional flag when running the dev server or distribution build. For example, yarn dev --theme=red or yarn build --theme=red.

When you include the theme flag, the node build scripts attempt to locate a corresponding file in src/scss. The file must also contain a -theme.scss moniker, for example, red-theme.scss.

The default project includes three themes:

ForgeRock default theme
ForgeRock dark theme yarn dev --theme=dark
ForgeRock rock theme yarn dev --theme=rock. This theme demonstrates how to use a full background image, with fallback to the default theme.

Build command summary

Inside of the packages folder of the monorepo you will find each stand alone project. These stand alone projects all rely on similar commands, on occation there are minor differences (for example theming doesn't apply to admin). Please check and package.json to see the specific commands. Here is a list of the universal commands.

# install dependencies
yarn

# serve with hot reload at localhost:8080 (increments by 1 automatically if port is in use).
yarn dev

# server with theme loaded (not admin)
yarn dev --theme=red

# build for production with minification
yarn build

# build with theme loaded (not admin)
yarn build --theme=red

# run all tests
yarn unit

Browser support

Latest Edge
Latest Firefox
Latest Safari
Latest Chrome

exAphex/platform-ui