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.

Table of contents

• 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 node version 14 or higher, or verify your node version node -v in your terminal. Your Node.js version should be >=14.
• This project uses a specific version of Yarn (3.6.1) that is bundled with the project in .yarn/releases. It's not required to install Yarn globally for this project, but if you are interested in how Yarn works or if you plan to use your own Yarn version, you can learn more about installing Yarn here. You can verify the yarn version running yarn -v in your terminal.
• 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 compat - Vue 3 migration build
• 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
• Pinia / 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