@rewardops/rewardops-ng v1.0.0-6

rewardops-ng

An library of Angular components for creating an app to interact with your RewardOps catalog.

Installation

This project requires Angular 6 or higher, Node 8.9.4 or higher, and NPM 3 or higher.

If you haven't installed angular-cli, do so:

  npm install -g angular-cli

You can install rewardops-ng into an Angular project with

npm install @rewardops/rewardops-ng@X.X.X

where vX.X.X is the version number you wish to install.

Importing the library

You can import the public API of the Typescript library by importing paths under @rewardops/rewardops-ng. For a list of available imports, see src/lib/public_api.ts.

Built JS packages are available in the dist/bundles folder.

Scss files are available in the scss folder. Compiled css is available in dist/css.

Images are available in dist/rewardops-assets. Add this folder to your load paths so that library components can access necessary images.

Angular Configuration

A sample config file is provided in environment.sample.ts. For first time setup refer to the sample config file and create a file environment.ts with your config values. During the build process Angular CLI will load the file environment.{env}.ts and by default will load environment.ts which you have created.

To configure rewardops-ng, pass the environment and api config instances created in your environment.ts or environment.$(NODE_ENV).ts in the providers in your main app module.

// src/app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { HttpClientModule } from '@angular/common/http';

// App config
import { environment, api } from '../environments/environment';
import { RewardOpsEnvConfig, RewardOpsApiConfig } from '@rewardops/rewardops-ng';

// App Root
import { AppComponent } from './app.component';

import { RewardOpsAppModule } from '@rewardops/rewardops-ng';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    HttpClientModule,
    RewardOpsAppModule
  ],
  providers: [
    { provide: RewardOpsEnvConfig, useValue: environment },
    { provide: RewardOpsApiConfig, useValue: api }
  ],
  bootstrap: [AppComponent]
})

export class AppModule { }

Information about the configuration objects' keys and values are located in the src/app/core/config folder. There you can find the class definition of the environment and api configuration objects, as well as ConfigService - a singleton service that loads and stores the config values in runtime, so other components and services throughout the app can make references when needed.

Env Config

API Config

Styles

You can import the rewardops-ng styles into your project by importing them in your app's main styles.scss.

@import "~@rewardops/rewardops-ng/scss/rewardops";

Theming

You can override the styles in rewardops-ng by creating a file src/_rewardops-overrides.scss in your app with your own values for any of the scss variables used in the library. Import your overrides file before the rewardops-ng styles in your styles.scss and the values will be applied in the rewardops-ng scss.

@import "rewardops-overrides";

@import "~@rewardops/rewardops-ng/scss/rewardops";

To see what variables are available, look at the file src/lib/_variables.scss.

User Authentication

User authentication in this application is implemented with Json Web Tokens.

All frontend authentication logic is handled in core/auth/auth.service.ts, which is designed to work with token based authentication methods and store the tokens in the browser's local storage.

Note: In the backend database, user passwords are stored as plaintext. It is strongly recommended to further salt and hash the passwords before storing them.

Securing API Routes

On the backend, auth is provided as an additional callback to each router method and behaves just like a middleware, as a pre-condition on the route. To disable jwt authentication for the particular route or if you wish to use another authentication method, simply remove auth from the method parameters and implement other authentication logic.

Sample implementation:

var jwt = require('jsonwebtoken');
var expressJwt = require('express-jwt');

// **Additional information like client id can also be incorporated into the token signature
var auth = expressJwt({secret: 'client-secret'});

router.get('/users/:id', auth, function(req, res) {
  // ...
});

Development

Publishing the package

To publish the library to npm:

• Update the version number in package.json (for this repo as a whole) and projects/rewardops-ng/package.json (for the published, built library).
• Commit the change.
• Tag the commit with the version number (e.g., git tag v1.0.0-5, where -5 signifies that this is the fifth pre-release version of 1.0.0). NOTE: The library version numbers follow the semantic versioning (SemVer) specification.
• Push the commit and the tags (i.e., git push && git push --tags).
• Run npm run build, which builds the library and copies its assets to dist/rewardops-ng.
• From the built library directory dist/rewardops-ng, run npm publish. NOTE: You must be logged into npm locally as the rewardops npm user to publish the library, as this is a private package.

npm run build
cd dist/rewardops-ng
npm publish

Testing

Unit tests

Run npm run test to execute the unit tests via Karma, and automatically rerun them when you save project files.

Tests can be run once (e.g., in a CI environment) using npm run test:single-run.

End-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor. Before running the tests make sure you are serving the app via ng serve.

Workflow

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive/pipe/service/class.

Styling

This project uses Bootstrap 4 for styling, and ngx-bootstrap for bootstrap component logic implemented in Angular.

Most scss variables can be found in src/lib/_variables.scss and are referenced throughout the app. All variables should be declared in this file with the !default flag, to allow users to override them.

Each Angular component also has its own scss file for component-specific styles. Note that the library does not use Angular view encapsulation, as this would restrict users from being able to override the library's variables in a custom _rewardops-overrides.scss. Each top-level directory in src/lib includes a scss partial with the same name as the directory. That partial imports the different scss files for each nested component. Those partials are then exported from the library in the directory scss.

Linting TypeScript

Running ng lint will run the lint npm script by default, which uses tslint. You can modify these scripts in package.json to run the tools of your choice

Internationalization

Mark text with the i18n attribute

Place the i18n on every element tag whose fixed text should be translated. For example:

<h1 i18n="<optional meaning>|<optional description>">Hello i18n!</h1>

To add Internationalization to attributes use i18n-x tags

Where x is the name of the attribute. For example:

<img [src]="logo" i18n-title title="logo" />

How-to:

To achieve Internationalization with Angular, we need to add the i18n tag to all the texts which require translation. And then you build a translation source file (messages.xlf) which has source and target tags for each entry with the i18n tag. The source tags are the english/default text and we populate the target tags with the translated text. Here is a sample message.xlf file:

<trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
  <source>Hello i18n!</source>
  <target>¡Hola i18n!</target>
  <note priority="1" from="description">Provided description</note>
  <note priority="1" from="meaning">Provided meaning</note>
</trans-unit>

Steps to do Internationalization:

• Mark text with the i18n attribute
• Create a translation source file with the ng-x18n tools
• Fill in the target values in the source file (separate file for each language)
• Merge the completed translation file into the app

For more information on how to handle singular/plural translations, gender based translations and building the message.xlf for each language, refer to Angular Internationalization

Style guide

Naming conventions

All component and module classes available for import via the public API should be named with the prefix RewardOps, with a filename prefixed with rewardops-.

Component selectors available via the public API should be prefixed with ro-.

CSS classes on public components should also be prefixed with ro-.

A contrived example:

// src/lib/rewardops-widget/rewardops-widget.component.ts

import { Component, ViewEncapsulation } from '@angular/core';

@Component({
  selector: 'ro-widget',
  templateUrl: './rewardops-widget.component.html',
  encapsulation: ViewEncapsulation.None
})
export class RewardOpsWidget {
  constructor() { }
}

<!-- src/lib/rewardops-widget/rewardops-widget.component.html -->

<p class="ro-widget__content">
  Just some content for this fancy widget.
</p>

CSS

This project follows BEM for CSS class names. (See the RewardOps CSS styleguide for more details.

In tests, do not use as test hooks CSS classes used for styling. Instead, add a separate class to the element following BEM naming conventions but prepended with the namespace test__.

Angular Style Guide

We follow the official Angular style guide: Official Angular Style Guide

Authors

• Michael Yeung - mike@rewardops.com
• Yathirajan Manavalan - yathi@rewardops.com
• Jerad Gallinger - jerad@rewardops.com