Getting Started

This document briefly describes the necessary steps to get started with Blueriq frontend development using the Angular framework from scratch. Below instructions are targeting Angular 10.

Installation

Working with a Blueriq frontend requires the following tools to be installed on your system.

Node.js

You need Node.js to start developing an Angular application. Download the LTS version and run to installer. Alternatively, consider using NVM (for *nix or Windows) for running multiple versions of Node next to each other.

Verify that everything works by running node --version followed by npm --version. Both commands should complete successfully and show the respective tool versions.

Angular CLI

The Angular team provides a tool to easily get started with Angular development, the Angular CLI. Install it using:

npm install --global @angular/cli

Verify that it works by running ng --version.

Dependencies

To include the Blueriq libraries in your application, you need to add them to the package.json file in the root of the project. This file describes all necessary dependencies to be installed.

The Blueriq library is bundled in multiple packages, @blueriq/core, @blueriq/angular and @blueriq/devtools. Add both to the list of "dependencies" of package.json with their latest version.

{
  // ...
  "dependencies": {
    // ...
    "@blueriq/core": "0.0.0",
    "@blueriq/angular": "0.0.0",
    "@blueriq/devtools": "0.0.0"
    // ...
  }
  // ...
}

You must configure NPM to resolve the @blueriq libraries from Blueriq's private artifactory. See Artifactory documentation for details.

Also add the following dependencies that are required by Blueriq's Angular framework:

{
  // ...
  "dependencies": {
    // ...
    "@ngrx/store": "^13.2.0",
    "@ngrx/effects": "^13.2.0"
    // ...
  }
  // ...
}

Please align the version of NgRx with the major version of Angular you're using.

Now install the newly added dependencies using npm install.

Proxy Configuration

Please refer to the proxy configuration page for details on how to configure a proxy server to connect with a Blueriq Runtime.

Import Modules

Angular uses a modular system to define components and services, such that for example a certain feature can be self-contained within an Angular module. In @blueriq/angular a module is provided that includes all required Blueriq functionality. Navigate to AppModule and ensure it at least contains the below imports:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BlueriqModule } from '@blueriq/angular';
import { V2BackendModule } from '@blueriq/angular/backend/v2';
import { DevtoolsModule } from '@blueriq/angular/devtools';
import { DateFormats } from '@blueriq/core';
import { EffectsModule } from '@ngrx/effects';
import { StoreModule } from '@ngrx/store';
import { AppComponent } from './app.component';
import { provideDateFormats } from './dates';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    StoreModule.forRoot({}),
    EffectsModule.forRoot([]),
    BlueriqModule.forRoot(),
    V2BackendModule.forRoot({
      baseUrl: '/Runtime',
    }),
    DevtoolsModule.forRoot({
      devtoolsUrl: '/devtools',
      runtimeUrl: '/Runtime',
      targetOrigin: '*',
    }),
  ],
  providers: [
    { provide: DateFormats, useFactory: provideDateFormats },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {
}

Also add a file dates.ts that implements logic to parse and formats date. The following example is implemented using moment.js, but you can use any library you like.

import { DateFormattingLibrary, DateFormats } from '@blueriq/core';
import * as moment from 'moment';

export function provideDateFormats(): DateFormats {
  return new DateFormats(new MomentDateFormatting(), {
    date: 'DD-MM-YYYY',
    time: 'HH:mm:ss',
    dateTime: 'DD-MM-YYYY HH:mm:ss'
  }, 'en-US');
}

export class MomentDateFormatting implements DateFormattingLibrary {

  format(date: Date, dateFormat: string, languageCode: string): string {
    return moment(date).format(dateFormat);
  }

  parse(value: string, dateFormat: string, languageCode: string): Date | null {
    const date = moment(value, dateFormat);

    return date.isValid() ? date.toDate() : null;
  }

}

We specify the baseUrl as configuration of the V2BackendModule, such that all Runtime calls will be using this base URL. The proxy configuration created earlier causes these requests to be proxied to the actual Runtime. To keep things simple, we use /Runtime because that is what Blueriq Runtime uses as the default cookie-path if running on an application server such as Tomcat. Since our simple proxy server does not rewrite the cookie-paths in Blueriq's responses we must assure that we send all requests to /Runtime as well in order for the Cookie to be passed by the browser.

The above example also configures DevtoolsModule to allow the development tooling support to work if the devtools query parameter is present. The exact configuration may depend on where the devtools UI is hosted; consider changing the devtoolsUrl accordingly or setup a proxy redirect for the devtools UI.