AngularJS – Spikes Apps

Securing an Angular application with Azure AD

Joren Paps — Thu, 27 Jul 2017 11:33:39 +0000

In this post, I’ll guide you through setting up a new Angular app and configuring it to use Azure AD authentication. This will be as much about the structure of the app itself as it will be about the security setup. The post consists of three main parts:

Create the base application structure
Configure and implement Azure AD authentication
Call a secured Web API

I won’t be using any CSS/UI frameworks so the app itself will look pretty crude. But at the end of this post, you should have a solid barebones app to build upon. Spruce it up with some bootstrap/material/… and you’ll be golden.

Laying the foundations

First, let’s create a new Angular app. We will use the Angular CLI for this, so open up a command prompt and run the ‘ng new’ command.

ng new AdalSample

Now that we have our app, let’s open the folder with VS Code (or your editor of choice) and get going.

The basic structure

Let’s start by creating a new component called ‘main’. This will be the root component for the functional part of our application. It will contain the shared layout for the application (navigation, header, footer…).

ng g component Main

Open up the main.component.html and copy/past the snippet below. The most important part here is the ‘router-outlet’ tag. Our content will get injected after this tag.

  Home

Next is the home component. This will be the landing page for our application.

ng g component main/Home

Before moving on to the next part we also have to replace the content of app.component.html with a router-outlet tag.

Keeping order

When we open the app.module, we’ll see that the Angular CLI automatically adds new components to the declarations array. It also creates a separate import line for each component. We currently only have two components in larger applications, this can become quite a list. We can remedy this by using a barrel to group our components together.

Barrels are files with a fixed name (index.ts), that contain exports of other files. They are a great way to keep import statements to a minimum or to group imports (for example rxjs operator imports). So let’s create one in the app folder.

export * from './app.component';export * from './main/main.component';export * from './main/home/home.component';

Now we can import the barrel and have all our component imports on one line. While we’re in the app.module, let’s make sure the router module is imported. Otherwise our router-outlet won’t work.

import { Route, RouterModule } from '@angular/router';import * as c from './';@NgModule({  imports: [BrowserModule,RouterModule  ],  declarations: [c.AppComponent,c.MainComponent,c.HomeComponent  ],  providers: [],  bootstrap: [c.AppComponent]})export class AppModule { }

Routing

We still need to tell our application how to use our newly created components. Routing can be configured straight in the app.module, but we will be using a separate file to house our route configuration.

Create a new typescript file called ‘app.routing.ts’ in the app folder and paste the code below into it.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import { MainComponent, HomeComponent } from './';const routes: Route[] = [{ path: '', component: MainComponent, children: [  { path: '', component: HomeComponent },]}];export const AppRoutes: ModuleWithProviders = RouterModule.forRoot(routes);

Now all that’s left is adding the AppRoutes constant to the app.module imports. If we start the development server and navigate to localhost:4200, we’ll see the ‘home works!’ message.

Error pages

A good app needs to have error pages. So let’s start by creating a 404 page. I’m using a separate module for the error pages to make use of lazy loading.

ng g module ErrorPages

ng g component error-pages/NotFound

Just like in the app.module, we also have to define the routing for our new module. Create a new file called ‘error-pages.routing.ts’ and add the code below. Don’t forget to add the ErrorPagesRoutes to the error-pages.module imports.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import * as c from './';const routes: Route[] = [{ path: '404', component: c.NotFoundComponent }];export const ErrorPagesRoutes: ModuleWithProviders = RouterModule.forChild(routes);

For our 404 to work, we also need to add some routes to the app.routing file. The ** path in the last route is a wildcard that matches any route that isn’t defined.

const routes: Route[] = [{ path: 'error', loadChildren: 'app/error-pages/error-pages.module#ErrorPagesModule'},{ path: '', component: MainComponent, children: [  { path: '', component: HomeComponent },]},{ path: '**', pathMatch: 'full', redirectTo: 'error/404' }];

If we go back to our website enter a non-existing URL in the address bar, our 404 page is shown. So far, so good.

Authentication

Authentication is done via the Azure Active Directory Authentication Library (ADAL) created by Microsoft. However, we won’t be using Microsoft’s ADAL.js directly, instead we’ll use an Angular wrapper library for ADAL. That way, we can skip over a lot of the boiler plate code. The one we’ll be using in this example is adal-angular4, so let’s go ahead and add the package to our solution.

npm i adal-angular4 --save

Once installation is complete, open up the app.module and add the imports below.

import { Http, HttpModule } from '@angular/http';import { Adal4Service, Adal4HTTPService } from 'adal-angular4';

To allow the Adal4Service to be injected into our components, we need to add it to the providers array.

  providers: [Adal4Service,{provide: Adal4HTTPService,useFactory: Adal4HTTPService.factory,deps: [Http, Adal4Service]}  ],

The Azure part

Now we need to make Azure aware of our app. Go to the Azure portal and select the Azure Active Directory blade. Under App Registrations, create a new App Registration.

The name you enter here will be displayed on the login screen, so choose something friendly. For the remaining fields, select ‘Web app / API’ and enter the Angular development server URL.

Do not close the Azure portal just yet, we’ll come back to it in a minute.

Setting up ADAL

Back in our Angular project, it is now time to add our ADAL configuration to the environments file(s). The CLI creates two environment files by default. One for production (when building with the –prod switch) and one for everything else.

Open the environments.ts file and add an adalConfig entry as shown. The tenant value can be found in the Azure Active Directory blade under ‘Domain names’. For the clientId we need to go back to the App Registrations list. Open the registration we just created and copy the Application ID guid.

export const environment = {  production: false,  adalConfig: {tenant: 'my-tenant.onmicrosoft.com',clientId: '00000000-0000-0000-0000-000000000000'postLogoutRedirectUri: 'http://localhost:4200/logout'  },};

Now we’re ready to enable authentication for our app. Open the app.component and change it to the the following.

import { Component, OnInit } from '@angular/core';import { Adal4Service } from 'adal-angular4';import { environment } from '../environments/environment';@Component({  selector: 'app-root',  templateUrl: './app.component.html',  styleUrls: ['./app.component.css']})export class AppComponent implements OnInit {  constructor(private adalSvc: Adal4Service) {this.adalSvc.init(environment.adalConfig);  }  ngOnInit(): void {this.adalSvc.handleWindowCallback();  }}

The init call speaks for itself. It initializes the ADAL service using the settings in our environment file. The handleWindowCallback call will extract the bearer token from the URL when Azure returns to our application after sign-in.

At this point, we’ve fully configured the ADAL service, but when we run the application we won’t see any change just yet.

Login / Logout

It is now time to enable login for our application. For this purpose we will create two additional pages.

ng g component Login

ng g component Logout

The actual logging in is handled by Azure, I hear you think. So why do we need a login page in our application? Well, the name says it all. This is going to be the page where we will call the ADAL login function. Additionally it serves as a splash screen of sorts. So the user won’t see a flash of the actual application before being redirected to the Azure login page.

You’ll see I’ve also included the option to provide a return URL in the querystring. This will be used by our authentication guard. If we didn’t have this in place, the user would always end up on the home screen after logging in.

import { Component, OnInit } from '@angular/core';import { ActivatedRoute, Router } from '@angular/router';import { Adal4Service } from 'adal-angular4';@Component({  selector: 'app-login',  templateUrl: './login.component.html',  styleUrls: ['./login.component.css']})export class LoginComponent implements OnInit {  constructor(private route: ActivatedRoute,private router: Router,private adalSvc: Adal4Service  ) { }  ngOnInit() {const returnUrl = this.route.snapshot.queryParams['returnUrl'] || '/';if (this.adalSvc.userInfo.authenticated) {  this.router.navigate([returnUrl]);} else {  this.adalSvc.login();}  }}

Next is the logout page. When the user clicks the logout link, this will be the place they’re sent. This will also be the page Azure redirects to after logging out. We set the redirect using the ‘postLogoutRedirectUri’ property in the Adal configuration.

As you can see in the code, the only thing that happens here is the logout call. Like with the login page, a reason for keeping this in a separate component is to have a splash screen to show between the time the user clicks logout, and the redirect to Azure.

import { Component, OnInit } from '@angular/core';import { Adal4Service } from 'adal-angular4';@Component({  selector: 'app-logout',  templateUrl: './logout.component.html',  styleUrls: ['./logout.component.css']})export class LogoutComponent implements OnInit {  isAuthenticated = false;  constructor(private adalSvc: Adal4Service  ) {this.isAuthenticated = this.adalSvc.userInfo.authenticated;  }  ngOnInit() {if (this.isAuthenticated) {  this.adalSvc.logOut();}  }}

In the markup we set different messages to show based on the status of the user (authenticated or not).

Signing out...  Signed out successfully. Click here to log back in.

To test the logout page, we also have to add a logout link to our main.component.

  Home  Logout

And before moving on, we still need to clean up some things. As usual, the CLI has already added our new components to the app.module. But we’re using a barrel, remember?

So first add the new components to our barrel in the app folder and correct the declarations in the module. The now unused imports can be removed.

export * from './app.component';export * from './login/login.component';export * from './logout/logout.component';export * from './main/main.component';export * from './main/home/home.component';

  declarations: [c.AppComponent,c.MainComponent,c.HomeComponent,c.LoginComponent,c.LogoutComponent  ],

Securing content

We’ve done a lot of setup work up to this point. But, this is where we will actually see everything come together.

To secure our main component and everything below it, we’re going to use a guard. This is nothing more than a class that implements some interfaces. Angular provides four interfaces for protecting routes.

CanActivate
CanActivateChild
CanDeactivate
CanLoad

For our app, we will only use CanActivate and CanActivateChild. If you want a more in depth explanation, Pascal Precht has a very nice post on guards.

First, let’s create a new folder called ‘common’ with a subfolder ‘guards’. In the guards folder, we create a new file called ‘authentication-guard.ts’ with the following content.

import { Injectable } from '@angular/core';import { Router, CanActivate, CanActivateChild, ActivatedRouteSnapshot, RouterStateSnapshot } from '@angular/router';import { Adal4Service } from 'adal-angular4';@Injectable()export class AuthenticationGuard implements CanActivate, CanActivateChild {  constructor(private router: Router,private adalSvc: Adal4Service  ) { }  canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {if (this.adalSvc.userInfo.authenticated) {  return true;} else {  this.router.navigate(['/login'], { queryParams: { returnUrl: state.url } });  return false;}  }  canActivateChild(childRoute: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {return this.canActivate(childRoute, state);  }}

When any of the CanActivate methods get called, our guard checks whether the user is logged in. If the user needs to login, it will redirect to our login page with the current route’s URL in the querystring.

For all this to work, we still need to do two things. Add our guard to the providers array in our app.module and register it on some routes.

  providers: [Adal4Service,{provide: Adal4HTTPService,useFactory: Adal4HTTPService.factory,deps: [Http, Adal4Service]},AuthenticationGuard  ],

const routes: Route[] = [{ path: 'error', loadChildren: 'app/error-pages/error-pages.module#ErrorPagesModule'},{ path: 'login', component: LoginComponent },{ path: 'logout', component: LogoutComponent },{ path: '', component: MainComponent, canActivate: [AuthenticationGuard], canActivateChild: [AuthenticationGuard], children: [  { path: '', component: HomeComponent },]},{ path: '**', pathMatch: 'full', redirectTo: 'error/404' }];

Our guard will get called when the user navigates to the main component or one of it’s child routes.

When running the application, you will see that the functional part of our application now requires authentication, while things like the error pages, login and logout are reachable without logging in.

Getting data

Now that we’ve secured our application, it is time to get some data. For that purpose, I have a secure WebAPI hosted in Azure that returns some hard-coded employee data. I won’t go into detail on how to set up a WebAPI since it not in the scope of this post. Koen has written an excellent post on how to do this.

The setup

To make use of Angular’s lazy loading, we will create a new module to group everything employee related. Organising your application into functional blocks like this has the added benefit of having components, services and models in close proximity.

First we’re going to create the module, the list component and the service class.

ng g module main/Employee

ng g component main/employee/List

ng g service main/employee/Employee

Next is our employee model. Add a folder ‘models’ in the employee folder and create a new file called ’employee.ts’. Copy the snippet below and save.

export interface IEmployee {  id: number;  name: string;  function: string;}export class Employee implements IEmployee {  id: number;  name: string;  function: string;  constructor(obj?: IEmployee) {if (obj) {  Object.assign(this, obj);}  }}

Normally I would also create barrels in the ’employee’ and ‘models’ folders. But since this example won’t get any extra functionality, we will skip the barrels.

Create a file called ’employee.routing.ts’ And add the route to the list component.

import { ModuleWithProviders } from '@angular/core';import { Route, RouterModule } from '@angular/router';import { ListComponent } from './list/list.component';const routes: Route[] = [{ path: '', component: ListComponent }];export const EmployeeRoutes: ModuleWithProviders = RouterModule.forChild(routes);

We still need to link everything up, so open up the employee module and add the EmployeeRoutes and EmployeeService.

import { NgModule } from '@angular/core';import { CommonModule } from '@angular/common';import { EmployeeRoutes } from './employee.routing';import { EmployeeService } from './employee.service';import { ListComponent } from './list/list.component';@NgModule({  imports: [CommonModule,EmployeeRoutes  ],  declarations: [ListComponent  ],  providers: [EmployeeService  ]})export class EmployeeModule { }

And lastly, add a link to our employee list and that’s it for the setup.

  Home  Employees  Logout

The implementation

For the service implementation, we have it pretty easy. Adal-angular4 will do almost everything for us. But first we need to make Adal aware of our api and that requires we make some changes in our environments file.

export const environment = {  production: false,  adalConfig: {tenant: 'my-tenant.onmicrosoft.com',clientId: '00000000-0000-0000-0000-000000000000'postLogoutRedirectUri: 'http://localhost:4200/logout',endpoints: {  'https://adaltestapi.azurewebsites.net': 'https://adaltestapi.azurewebsites.net'},  },  apiUrl: 'https://adaltestapi.azurewebsites.net/api/'};

The ‘apiUrl’ is for use in our service and it contains the base URL of our WebAPI. For service authentication to work correctly, we also need to add our API to the endpoints in our Adal configuration. The endpoints value is an object with key/value pairs for each resource the application uses. The key is the resource URL and the value is the App ID URI. You can find this value in the Azure portal under the app registration settings of your API.

Now on to the service itself. We do essentially the same as we normally do, but instead of Angular’s Http, we use the Adal4HTTPService. This wrapper works virtually the same as Http, but it will automatically add the bearer token to the request. But only if the request URL is defined as an endpoint.

import { Adal4HTTPService } from 'adal-angular4';import { environment } from '../../../environments/environment';import { Employee, IEmployee } from './models';@Injectable()export class EmployeeService {constructor(private http: Adal4HTTPService  ) { }  public getEmployees(): Observable> {return this.http.get(`${environment.apiUrl}Employee`)  .map(response => {const tmp = response.json();return tmp.map(e => new Employee(e));  });  }}

All that is left, is to call our service and show the data on screen. This is exactly the same as you’re used to.

export class ListComponent implements OnInit {  employeeList: Array = [];  constructor(private empSvc: EmployeeService  ) { }  ngOnInit() {this.empSvc.getEmployees().subscribe(  rslt => this.employeeList = rslt,  error => console.log(error));  }}

Employees
Id Name Function
{{emp.id}} {{emp.name}} {{emp.function}}

Id	Name	Function
{{emp.id}}	{{emp.name}}	{{emp.function}}

Conclusion

And that is it. Using Adal with Angular is pretty easy when using a wrapper like adal-angular4. But as I said in the intro, this post is mostly about providing a decent starting structure for the types of business apps a lot of us typically work on. The biggest advantage I find, is that authentication code is centralised. None of the components under main have to know anything about Adal, Azure or security. All this is handled far away from the business and UI logic, which makes for an easier to maintain application.

The source code of the sample projects can be found on our GitHub.

Joren Paps

Senior Developer @ Spikes

Optimize performance of your SharePoint Online portal

Tom De Groote — Fri, 16 Dec 2016 13:10:28 +0000

When customers want an intranet portal, they sometimes insist upon a landing page with a lot of content. Additionally, the page must be very attractive and the content needs to be targeted based upon user profile properties to ensure that the users are presented with the information that is most valuable for them.

This results in a lot of requests to build the page. If your customer has offices all around the world, this is even more difficult because the network performance can be very different.

In this post, I’ll give a overview of the performance optimizations to the solutions that we implemented for our customers to reduce the number and the size of requests to build the page.

Performance enhancements

The Microsoft support article Introduction to performance tuning for SharePoint Online offers a good starting point. Some of the tips below are coming from that article. Other tips are coming from our own experience or from the code reviews we got from Microsoft.

jQuery.getScript

Be careful when using jQuery.getScript to load scripts dynamically. This function adds a timestamped query parameter to each request to enforce the reload of the script:

/js/v1/SpikesHelper.js?_=1459511141746

Because of this query parameter, the browser cache will never be used, not even if you would load the same script multiple times on the same page.

If you want to cache the script, you have to set the cache property globally using $.ajaxSetup() or create your own method to load the scipts using $.ajax().

More information can be found in the jQuery documentation.

Another alternative could be using a loading framework such as RequireJS.

SP.RequestExecutor

If you want to make cross domain calls in SharePoint, you can use SP.RequestExecutor. However, don’t use SP.RequestExecutor for every call because this will always result in an extra /_api/contextinfo request before the postQuery request.

if (onHostWeb) {  window.SpikesHelper.getCachedScript(scriptBase + "SP.RequestExecutor.js",   function () {var executor = new SP.RequestExecutor(window.DataProvider.HostWebUrl());executor.executeAsync({  url: searchCallUrl,  method: "POST",  headers: {"accept": "application/json;odata=nometadata","content-type": "application/json; odata=verbose","X-RequestDigest": $('#__REQUESTDIGEST').val()  },  success: onSearchSuccessRest,  error: onSearchFailRest})  });}else {  $.ajax({'url': searchCallUrl,'type': "POST",'headers': {  "accept": "application/json;odata=nometadata",  "content-type": "application/json; odata=verbose",  "X-RequestDigest": $('#__REQUESTDIGEST').val()},'success': function (data) {  onSearchSuccessRest(data);},'error': onSearchFailRest  });}

Local storage

Use your browser’s local storage to cache information that doesn’t change frequently such as user profile properties or managed metadata.

Since it may sometimes be necessary to clear this local storage, I suggest providing a button to do this.

saveToStorage: function (key, data, expirationSeconds) {  "use strict";  var expirationMS = expirationSeconds * 1000,record = { value: data, timestamp: new Date().getTime() + expirationMS };  localStorage.setItem(key, JSON.stringify(record));  return data;},loadFromStorage: function (key) {  "use strict";  var record = JSON.parse(localStorage.getItem(key));  if (!record) {return null;  }  if (new Date().getTime() < record.timestamp) {  return record.value;   }   // The entry has expired, so remove from local storage   localStorage.removeItem(key);   return null; }, clearStorage: function () {   for (var i = localStorage.length - 1; i >= 0; i--) {if (localStorage.key(i).startsWith('Spikes')) {  localStorage.removeItem(localStorage.key(i));}  }}

REST batching

Where possible, execute REST commands in batches. You can for instance use Steve Curran’s REST batch executor.

JSON light

You can significantly reduce the payload of your REST request with JSON Light as stated in this blog post.

If you have existing code that uses odata=verbose, be aware that you also have to change the parsing of the results because the format of the returned JSON is different.

In some cases, for instance if you want the edit link of an item, odata=nometadata doesn’t provide enough information and we had to use odata=minimalmetadata.

Search queries

If you need to implement targeting, where possible use search queries. It will take some time before new items become visible on the page, but the request for the data will be quicker since the search results are indexed.

If you have complex queries you might need to do a POST request instead of a GET request.

You can test the performance of your search queries using the SharePoint Search Query Tool.

CDN

Use an Azure CDN to host your own custom files. Not only scripts and CSS, but also the images for the branding. The content that is accessed from a CDN is much faster available than the content that is hosted in SharePoint Online.

For some types of files, such as fonts and html templates, you might need to set CORS headers because using a CDN will result in cross domain calls.

For files coming from Azure CDN, you can control the cache behaviour using the cache-control header depending on your environment. If you have clients with a very slow network, You might even consider to set the max-age to the maximum duration (max-age=31536000) and implement cache busting functionality, for instance using a loading framework such as RequireJS.

External script components can also be referenced from a CDN. Since a browser can only handle a number of request from the same host simultaneously, you could even reference external scripts from multiple CDN’s to improve the page load.

Bundling and minification

If you have multiple JavaScript and CSS files, you can bundle and minify those to reduce the number of requests as well as the size of the requests.

Image sprites

If you have a lot of small images in the branding, you can combine those into one image sprite.

Image renditions

Image renditions are slow in SharePoint because the rely upon the cache on the server. Since SharePoint Online is a huge farm with a lot of different servers, your request will probably be served by another server and it is not likely that you will get a cache hit.

SharePoint navigation

As stated in the support article Navigation options for SharePoint Online, you should never use structural navigation. Use search driven navigation or managed navigation instead.

If you are not using Quick Launch, it is best to disable this in Site Settings – Navigation Elements.

Asset library vs Style library

If you have to store files in SharePoint (for instance proprietary files that you don’t want to store on the CDN), consider using the asset library instead of the style library because the style library requires an extra authentication step.

Custom master page

A custom master page is not recommended, but should you still need it, consider adding an extra placeholder at the end of the body section to load your custom scripts.

Home page layout

Most of the time, we started our home page layout with web part zones and we add web parts to present the different components to the user. This provides a lot of flexibility when we want to adapt the home page.

If there are a lot of web part zones and web parts on the page however, it takes a long time for the server to build up that page. The server returns an SPRequestDurarion header that contains the server processing time in millisecond. For a publishing page with 8-10 web parts we observed times of 2-3 seconds and sometimes even more.

We implemented a home page layout based upon AngularJS and now the server processing time is down to 1 second and even less.

If still better performance would be necessary, the next step would perhaps be to build the home page in an Azure App web using the Office UI Fabric and linking from there to the SharePoint Online site.

Summary

When designing a landing page for an intranet portal, there are definitely a lot of things you can do to reduce the network traffic and server load.

–

Tom De Groote

Senior SharePoint Architect @ Spikes

–

Your new SharePoint playground

Rob Lempens — Tue, 22 Nov 2016 10:21:27 +0000

A SharePoint developer is becoming more and more a web developer. This has some big advantages but it also means that our daily work is changing a lot.
Considering all these changes it’s hard to keep up with the latest technologies.

This blog will give you an overview of the technologies and tools you can no longer ignore.

Yeoman
The web’s scaffolding tool for modern web apps.
<http://yeoman.io/>

Visual studio code
Visual Studio Code is a code editor redefined and optimized for building and debugging modern web and cloud applications.
<https://code.visualstudio.com/>

Office UI Fabric
The official front-end framework for building experiences that fit seamlessly into Office and Office 365.
<https://dev.office.com/fabric>

SPFx
SharePoint Framework—a Page and Part model that enables fully supported client-side development, easy integration with the Microsoft Graph and support for open source tooling.
<https://blogs.office.com/>

TypeScript
TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.
<https://www.typescriptlang.org/>

NPM
NPM is the package manager for JavaScript. Find, share, and reuse packages of code from hundreds of thousands of developers — and assemble them in powerful new ways.
<https://www.npmjs.com/>

NodeJs
Node.js is an open-source, cross-platform JavaScript runtime environment for developing a diverse variety of tools and applications.
<https://nodejs.org/>

React
A JavaScript library for building user interfaces
React (sometimes styled React.js or ReactJS) is an open-source JavaScript library providing a view for data rendered as HTML.
<https://facebook.github.io/react/>
<https://en.wikipedia.org/wiki/React_(JavaScript_library)>

NG2
Angular is a development platform for building mobile and desktop web applications.
<https://angular.io/>

Git
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
<https://git-scm.com/>

Gulp.js
Gulp is a streaming build system, by using node’s streams file manipulation is all done in memory, and a file isn’t written until you tell it to do so.
Much like Grunt, Gulp is a javascript task runner. Gulp however prefers code over configuration. Being that your tasks are written in code, gulp feels more like a build framework, giving you the tools to create tasks that fit your specific needs.
<https://scotch.io/tutorials/automate-your-tasks-easily-with-gulp-js>

ADAL
The Active Directory Authentication Library enables client application developers to easily authenticate users to cloud or on-premises Active Directory (AD), and then obtain access tokens for securing API calls.
<>

Bower
Bower is a package manager for the web. It offers a generic, unopinionated solution to the problem of front-end package management.
<https://bower.io/>

Summary:

“Be curious, try things, fail fast!” – Sebastian Levert

–

Rob Lempens

Developer @ Spikes

–

How to – Build your own Angular translation service – Part 3

Ruben B — Thu, 27 Oct 2016 16:48:53 +0000

Intro

As the title suggests, this post is part of a series. Be sure to read the first two parts:

I ended part two with resource classes containing dictionaries for the languages. In part three, I will get rid of those resource classes and replace them with json files.

Continue reading to find out the details.

Part 3

Once again I copied the end result of my previous solution and renamed everything so it’s clear that I’m working on part three.

Removing the resource classes

As I stated in the intro, I want to get rid of the actual resource classes and replace them with json files.

So, I want to go from:

import C = DeBiese.Common;export class HomeResources extends C.Resources.ResourceBase {constructor() {super('Home');}protected setLanguageDictionary(): void {const self = this;let Translations_en: Array> = [{ key: 'title', value: 'Home Title' },{ key: 'helloWorld', value: 'Hello World!' }];let Translations_nl: Array> = [{ key: 'title', value: 'Home Titel' },{ key: 'helloWorld', value: 'Hallo wereld!' }];self.languageDictionary = new C.Dictionary>([{ key: 'en', value: new C.Dictionary(Translations_en) },{ key: 'nl', value: new C.Dictionary(Translations_nl) }]);};}

To:

//home.en.json
[
{ "key": "title", "value": "Home Title" },
{ "key": "helloWorld", "value": "Hello World!" }
]

//home.nl.json
[
{ "key": "title", "value": "Home Titel" },
{ "key": "helloWorld", "value": "Hallo wereld!" }
]

This completely removes the need of the ResourceBase class. Having my translations available in json format enables me to load them using the Angular $http service. I will no longer be required to include the resource files on my index page, as there is no longer a Javascript file to include.

It brings forth another challenge however. How to tell my ResourceService which files to load.

ResourceFile

export class ResourceFile implements IResourceFile {fileLocation: string;keyPrefix: string;languages: Array;constructor(resource?: IResourceFile) {if (resource != null) {this.fileLocation = resource.fileLocation;this.keyPrefix = resource.keyPrefix;this.languages = resource.languages;}}}

The ResourceFile describes how I will configure the ResourceService going forward. One ResourceFile holds the information that was previously contained in a ResourceBase class.

fileLocation:
The folder path in which the json files are stored
keyPrefix:
The prefix that is used in the ResourceService when translations from this ResourceFile are added to it.
languages:
An array containing the languages that are supported by this ResourceFile. For each language defined in this array, a json file should exist in the folder indicated by the fileLocation.

ResourceConfiguration

export class ResourceConfiguration implements IResourceConfiguration {private $resourceFiles: Array;preferredLanguage: string = 'en';constructor() {this.$resourceFiles = [];}addResourceFile(file: IResourceFile): void {const self = this;self.$resourceFiles.push(file);}getResourceFiles(): Array{const self = this;return self.$resourceFiles;}}

The changes in the ResourceConfiguration are as expected.

$resourceFiles replaces $resources
addResourceFile replaces addResource
getResourceFiles replaces getResources

The main idea remains the same. We add ResourceFiles to the configuration which will result in loading translations into the ResourceService.

Typical usage of the ResourceConfiguration:

app.config((resourceServiceProvider: DeBiese.Common.Resources.ResourceProvider) => {let resourceConfig: DeBiese.Common.Resources.IResourceConfiguration = new DeBiese.Common.Resources.ResourceConfiguration();resourceConfig.preferredLanguage = 'en'; //is the default setting (could be omitted here)resourceConfig.addResourceFile(new DeBiese.Common.Resources.ResourceFile({ keyPrefix: 'Home', fileLocation: '/app/resources/components/home/', languages: ['en', 'nl'] }));resourceConfig.addResourceFile(new DeBiese.Common.Resources.ResourceFile({ keyPrefix: 'Help', fileLocation: '/app/resources/components/help/', languages: ['en', 'nl'] }));resourceConfig.addResourceFile(new DeBiese.Common.Resources.ResourceFile({ keyPrefix: 'Nav', fileLocation: '/app/resources/directives/navigation/', languages: ['en', 'nl'] }));resourceConfig.addResourceFile(new DeBiese.Common.Resources.ResourceFile({ keyPrefix: 'Error', fileLocation: '/app/resources/errors/', languages: ['en', 'nl'] }));resourceServiceProvider.config(resourceConfig);});

ResourceProvider

Because I choose to work with json files, I will need to load the data in those files at runtime. That means that I need to inject the $http service into my ResourceService. Knowing that the ResourceService is instantiated by the ResourceProvider, I needed to figure out how to inject the $http service in the ResourceProvider.

export class ResourceProvider implements ng.IServiceProvider {static id: string = 'resourceService';private $resourceService: ResourceService;private $resourceConfiguration: IResourceConfiguration;constructor() {this.$get.$inject = ['$http'];}public config(resourceConfig: IResourceConfiguration): void {this.$resourceConfiguration = resourceConfig;}public $get($http: ng.IHttpService): IResourceService {this.$resourceService = new ResourceService($http);this.$resourceService.configure(this.$resourceConfiguration);return this.$resourceService;}}

Injection in a Provider is done by injection into the $get function. In the constructor of the provider the $inject property can be set on the $get function.

Nothing else has changed in the ResourceProvider.

ResourceService

class ResourceService implements IResourceService {$inject: Array = ['$http'];private $resourceDictionary: Dictionary> = null;private $dictionary: Dictionary = null;private $loadedResourceFiles: Dictionary = null;constructor(private $http: ng.IHttpService) {this.$resourceDictionary = new Dictionary>();this.$dictionary = new Dictionary();this.$loadedResourceFiles = new Dictionary();}private loadResourceFile(resourceFile: IResourceFile): ng.IPromise {const self = this; let defer = Q.defer();let loadPromises: Array = [];if (!self.$loadedResourceFiles.containsKey(resourceFile.keyPrefix)) {resourceFile.languages.forEach(lang => {loadPromises.push(self.loadLanguageFile(resourceFile, lang));});} Q.all(loadPromises).then(() => {self.$loadedResourceFiles.add(resourceFile.keyPrefix, resourceFile);defer.resolve(true);});return defer.promise;}private loadLanguageFile(resourceFile: IResourceFile, languageToLoad: string): ng.IPromise {const self = this;let defer = Q.defer();self.$http.get(`${resourceFile.fileLocation}${resourceFile.keyPrefix.toLowerCase()}.${languageToLoad}.json`).success((data, status, headers, config) => {let resources: Dictionary = new Dictionary(data as Array>);let tmpDictionary: Dictionary = null;if (self.$resourceDictionary.containsKey(languageToLoad)) {tmpDictionary = self.$resourceDictionary.getValue(languageToLoad);}else {tmpDictionary = new Dictionary();self.$resourceDictionary.add(languageToLoad, tmpDictionary);}resources.keys().forEach(tr => {tmpDictionary.add(`${resourceFile.keyPrefix}.${tr}`, resources.getValue(tr));});defer.resolve(true);}).error((data, status, headers, config) => {//TODO: do something with this?console.log('ERROR:');console.log(data);defer.resolve(false);});return defer.promise;}addResourceFile(resourceFile: IResourceFile): void {const self = this;self.loadResourceFile(resourceFile);}configure(resourceConfig: IResourceConfiguration): void {const self = this;if (resourceConfig != null) {if (resourceConfig.getResourceFiles().length === 0)throw new Error('At least one resource file must be configured!');if (resourceConfig.preferredLanguage === '')throw new Error('A preferred language must be set');}else {throw new Error('Resource configuration can not be NULL!');}let loadPromises: Array = [];resourceConfig.getResourceFiles().forEach(rf => {self.loadResourceFile(rf);});Q.all(loadPromises).then(() => { self.setLanguage(resourceConfig.preferredLanguage); });}getLocalResource(resourceKey: string): string {const self = this;if (self.$dictionary.containsKey(resourceKey))return self.$dictionary.getValue(resourceKey);elsereturn resourceKey;}setLanguage(language: string): void {const self = this;if (self.$resourceDictionary.containsKey(language))self.$dictionary = self.$resourceDictionary.getValue(language);elsethrow new Error(`Language ${language} has not been configured!`);}}

Similar to part two, I will explain each piece of code. Where possible I’ll refer to part two and only highlight the difference this time around.

Declarations and constructor

The service now contains a third dictionary:

$loadedResourceFiles:
Used to store the ResourceFiles that are loaded in the service. This dictionary is added to support the loading of ResourceFiles at another time than during the configuration phase. An example of this follows later on in the Using the ResourceService

The constructor instantiates each dictionary as an empty dictionary.

AddResourceFile

Adds a single ResourceFile to the ResourceService by calling the private function loadResourceFile. Explanation of the private functions follows below.

Configure

I loop through all the ResourceFiles provided to the configure function and call the private function loadResourceFile for each one.

Because loading the json files is done using the $http service, this is an asynchronous action. The loadResourceFile function returns a promise. I collect each promise in an array and wait for each promise to return with Q.all before I set the language.

SetLanguage

There are no changes in this method.

GetLocalResource

I did one small change in this function. Instead of returning the string Unknown ResourceKey for an unknown key, I now return the key itself. I prefer to know which key is not found instead of just knowing that a certain key is not found.

LoadResourceFile

This function will initiate the load of the json files associated with the provided ResourceFile, if the $loadedResourceFile dictionary not already contains this ResourceFile.

I loop through each provided language and call another private function loadLanguageFile. This second private function will do the heavy lifting.

LoadLanguageFile

This function uses the $http service to get the data from the json file.

The json files should be named using the following naming convention: keyPrefix.language.json .
An example: home.en.json – home.nl.json

Once the data of the json file is returned, it is loaded into the $resourceDictionary.

Using the ResourceService

Usage of the ResourceService remains the same. The only exception is when I want to delay loading certain ResourceFiles.

In a large(r) application, it might be useful to not load all the ResourceFiles during the configuration phase of the application. When that’s the case, it might be an advantage to choose to load the ResourceFile of a certain component when this component is used the first time.

The $onInit function on the controller of a component is ideal in this scenario.

$onInit(): void {const self = this;self.resourceSvc.addResourceFile(new DeBiese.Common.Resources.ResourceFile({ keyPrefix: 'Home', fileLocation: '/app/resources/components/home/', languages: ['en', 'nl'] }));self.activate();}

Changing the language

I did not provide an actual implementation of changing the language in the sample code of part two. So, I added this in this part. Check out the Navigation directive in the application.

And that’s it. The Angular application is now translated using json files.

Summary

ResourceFile
ResourceConfiguration
- Use ResourceFile instead of ResourceBase classes
ResourceProvider
- Inject $http service
ResourceService
- Inject $http service
- Load json files
- Added option to add a ResourceFile later in the application.

Closing word

In this part I showed you how to use json files for the translations instead of dictionaries defined in code. I also provided a way of loading the translations when necessary so not every translation needs to be loaded during configuration.

In the next part I will focus on some nice to haves. The most important one will probably be a helper application for creating and editing the json files. Stay tuned!

The full code base of this little test project can be found on GitHub.

Feel free to comment down below!

Ruben Biesemans

Analyst Developer @ Spikes

How to – Build your own Angular translation service – Part 2

Ruben B — Tue, 18 Oct 2016 19:44:14 +0000

Intro

In part one, which you can find here, I covered centralizing static text in a resources folder.

In this second part, I will add support for multiple languages and I will build a service for using those translations throughout the application.

Let’s get started!

Part 2

Setting up the project

I pick up where I left in part one with my code. For the sake of clarity, I renamed my solution, project and modules to reflect that the code accompanies part two in this series.

Dictionaries

First thing to figure out is how to go from static string declarations to supporting multiple string values per declaration. Let me rephrase that.

How can I assign multiple possible text values to a single declared key and pick the right value for that key depending on the chosen language?

I chose to work with dictionaries containing key-value pairs. This means that I will use a dictionary containing all the supported languages with a key indicating the current language. The value part is also a dictionary which will hold a unique identifier of the translated text as key and the translated text itself as value.

An example will clear this all up:

There’s no such thing as a dictionary in Typescript, but it’s possible to implement one. In all fairness, I didn’t implement one myself, because I found an implementation that suits my needs right here.

I added a few things such as:

A constructor that takes an array of KeyValuePairs

constructor(values?: Array>) {if (values != null) {this.load(values);}}

A method clear that removes all items from the dictionary

public clear(): void {this._keys = [];this._values = [];}

A method load that also takes an array of KeyValuePairs which will be added to the dictionary. The load method optionally clears the dictionary first.

public load(values: Array>, clearDictionary?: boolean): void {const self = this;if (clearDictionary != null && clearDictionary == true)self.clear();values.forEach(kvp => {self.add(kvp.key, kvp.value);});}

I also created the KeyValuePair object that I used.

export class KeyValuePair{key: T;value: U;constructor(key: T, value: U) {this.key = key;this.value = value;}}

Resource Classes

The resource classes from part one need a complete rewrite. I wanted as little code as possible in the resource classes themselves. That’s why I created a ResourceBase class which contains all the code necessary to make the resource classes functional.

The base class:

export abstract class ResourceBase {protected resourceName: string;protected languageDictionary: Dictionary> = null;constructor(name: string) {this.resourceName = name;this.setLanguageDictionary();}protected setLanguageDictionary(): void {throw new Error('setLanguageDictionary not implemented!');};getLanguages(): Dictionary> {const self = this;return self.languageDictionary;}getResourceName(): string {const self = this;return self.resourceName;}getTranslations(language: string): Dictionary {const self = this;if (self.languageDictionary == null)self.setLanguageDictionary();if (self.languageDictionary.containsKey(language))return self.languageDictionary.getValue(language);elsethrow new Error(`Language '${language}' does not exist.`);}}

The base class holds a resourceName (string) and a languageDictionary (Dictionary). The methods that get information out of the class are implemented. The method that sets the information throws an error, because the classes implementing this base class are supposed to implement this part.

The resource class for my HomeComponent:

import C = DeBiese.Common;export class HomeResources extends C.Resources.ResourceBase {constructor() {super('Home');}protected setLanguageDictionary(): void {const self = this;let Translations_en: Array> = [{ key: 'title', value: 'Home Title' },{ key: 'helloWorld', value: 'Hello World!' }];let Translations_nl: Array> = [{ key: 'title', value: 'Home Titel' },{ key: 'helloWorld', value: 'Hallo wereld!' }];self.languageDictionary = new C.Dictionary>([{ key: 'en', value: new C.Dictionary(Translations_en) },{ key: 'nl', value: new C.Dictionary(Translations_nl) }]);};}

In the constructor I call the constructor of the base class, this sets the resourceName which will be used later on by our resource service. The resourceName will be used as a prefix when adding the dictionary of this one resource class into the global dictionary that is created in the ResourceService at runtime.

I override the setLanguageDictionary method and create a dictionary for every language I wish to support. Those language dictionaries are added to the languageDictionary of the resource class.

Resource Provider

I want to configure my resources before starting the application, so I’m creating a ResourceProvider. If you are not familiar with providers in Angular, you can find more information here.

export class ResourceProvider implements ng.IServiceProvider {static id: string = 'resourceService';private $resourceService: ResourceService;constructor() {this.$resourceService = new ResourceService();}public config(resourceConfig: IResourceConfiguration): void {this.$resourceService.configure(resourceConfig);}public $get(): IResourceService {return this.$resourceService;}}angular.module('debiese.common', []).provider(DeBiese.Common.Resources.ResourceProvider.id, DeBiese.Common.Resources.ResourceProvider);

The provider will hold an instance of my ResourceService and accepts a ResourceConfiguration object for configuration of the service.

Resource Configuration

export class ResourceConfiguration implements IResourceConfiguration {private $resources: Array;preferredLanguage: string = 'en';constructor() {this.$resources = [];}addResource(resource: ResourceBase): void {const self = this;self.$resources.push(resource);}getResources(): Array {const self = this;return self.$resources;}}

The ResourceConfiguration can be used to set the preferredLanguage of the application. By default this will be ‘en’ (English). Besides that, an array of ResourceBase instances can be added.

Typical usage of this configuration:

//Resource configurationapp.config((resourceServiceProvider: DeBiese.Common.Resources.ResourceProvider) => {let resourceConfig: DeBiese.Common.Resources.IResourceConfiguration = new DeBiese.Common.Resources.ResourceConfiguration();resourceConfig.preferredLanguage = 'en'; //is the default setting (could be omitted here)resourceConfig.addResource(new DeBiese.NgResources.Part2.Resources.HelpResources());resourceConfig.addResource(new DeBiese.NgResources.Part2.Resources.HomeResources());resourceConfig.addResource(new DeBiese.NgResources.Part2.Resources.NavigationResources());resourceConfig.addResource(new DeBiese.NgResources.Part2.Resources.ErrorResources());resourceServiceProvider.config(resourceConfig);});

Resource Service

export interface IResourceService {getLocalResource: (resourceKey: string, resourceFile?: string) => string;setLanguage: (language: string) => void;}class ResourceService implements IResourceService {private $resourceDictionary: Dictionary> = null;private $dictionary: Dictionary = null;constructor() {this.$resourceDictionary = new Dictionary>();}configure(resourceConfig: IResourceConfiguration): void {const self = this;if (resourceConfig != null) {if (resourceConfig.getResources().length === 0)throw new Error('At least one resource must be configured!');if (resourceConfig.preferredLanguage === '')throw new Error('A preferred language must be set');}else {throw new Error('Resource configuration can not be NULL!');}resourceConfig.getResources().forEach(rb => {if (rb.getLanguages() != null && rb.getLanguages().count() > 0) {let languageDictionary = rb.getLanguages();languageDictionary.keys().forEach(k => {let tmpDictionary: Dictionary = null;if (self.$resourceDictionary.containsKey(k)) {tmpDictionary = self.$resourceDictionary.getValue(k);}else {tmpDictionary = new Dictionary();self.$resourceDictionary.add(k, tmpDictionary);}let translationDictionary = languageDictionary.getValue(k);if (translationDictionary != null && translationDictionary.count() > 0) {translationDictionary.keys().forEach(tr => {tmpDictionary.add(`${rb.getResourceName()}.${tr}`, translationDictionary.getValue(tr));});}});}});self.setLanguage(resourceConfig.preferredLanguage);}getLocalResource(resourceKey: string): string {const self = this;if (self.$dictionary.containsKey(resourceKey))return self.$dictionary.getValue(resourceKey);elsereturn 'Unknown resourceKey';}setLanguage(language: string): void {const self = this;if (self.$resourceDictionary.containsKey(language))self.$dictionary = self.$resourceDictionary.getValue(language);elsethrow new Error(`Language ${language} has not been configured!`);}}

The last piece of the puzzle, the ResourceService. It’s important to point out that only the IResourceService interface is exported. This is not a typo or oversight on my part. This means that only the methods exposed through the interface are accessible in the application.

The configure method is called by the ResourceProvider during the configuration phase of the provider.

Let me explain the service piece by piece.

Declarations and constructor

The service contains two dictionaries:

$resourceDictionary:
Used to store each language with its respective dictionary of translations
$dictionary:
The currently active dictionary of translations. When the language is changed in the application, the value of this dictionary will change to reflect the chosen language

The constructor instantiates the $resourceDictionary as an empty dictionary.

Configure

First some basic checks are executed. Nothing fancy. Once past the checks, I start building up the $resourceDictionary by looping through each ResourceBase provided.

Each ResourceBase contains a languageDictionary. I loop through each language in this dictionary. If the $resourceDictionary already contains a dictionary for this language, I use it, otherwise I create a new dictionary and add it to the $resourceDictionary.

Now I loop through the dictionary for each language and add each translation into this one list. As said before, I add the resourceName of the ResourceBase class as a prefix.

SetLanguage

This simply sets the value of $dictionary if in fact the provided language exists in the $resourceDictionary. If not an error is thrown.

GetLocalResource

Returns the translation, value as you will, from the $dictionary for the provided (resource)Key if the key exists. Otherwise a default string ‘Unknown resourcekey’ is returned.

Using the ResourceService

To use the ResourceService in your component, you inject the ResourceProvider into your controller.

export class HomeController implements IHomeController {static $inject: string[] = ['$state','$timeout',S.ToastService.id,S.LogService.id,S.DummyService.id,DeBiese.Common.Resources.ResourceProvider.id];//...constructor(private $state: angular.ui.IStateService,private $timeout: ng.ITimeoutService,private toastSvc: S.IToastService,private logSvc: S.ILogService,private dummySvc: S.DummyService,private resourceSvc: DeBiese.Common.Resources.IResourceService) {//...}}

With the resourceSvc on the controller, we can use this in the controller itself like so:

self.$timeout(() => {self.toastSvc.toastError(self.resourceSvc.getLocalResource('Home.helloWorld'))}, 0, true);

Or in the view like so:

{{vm.resourceSvc.getLocalResource('Home.title')}}
{{vm.resourceSvc.getLocalResource('Home.helloWorld')}}

Notice that in the html I’m no longer using one-way binding. That’s because I want to be able to switch the language on the go. The translations should be loaded immediately. So one-way binding is no longer an option.

Changing the language

The last part is providing the user with a language picker. Changing the language in the picker should call the setLanguage method on the ResourceService. Translations will show up immediately.

And that’s it. I have a translated Angular application.

Summary

Helper classes
- KeyValuePair
- Dictionary
- ResourceBase
ResourceProvider
- Creates ResourceService instance
- Configures ResourceService during app configuration
- Is injected into controllers for usage in code or html

Closing word

In this part I built upon my centralized static text to introduce translations. In Part three I’ll be looking into separating the translations into json files and possibly lazy loading them instead of loading all translations at the start of the application. Stay tuned!

The full code base of this little test project can be found on GitHub.

Feel free to comment down below!

Ruben Biesemans

Analyst Developer @ Spikes

How to – Build your own Angular translation service – Part 1

Ruben B — Fri, 30 Sep 2016 05:31:26 +0000

Intro

This will be a first in a series of posts in which I will build a translation service for Angular from the ground up.

I want to point out up front that I know there are multiple angular translation libraries out there, like for instance angular-translate and angular-gettext, which are directly available for use. So, if you are looking for something to just plug into your application, that might be the way to go.

I’m going to explore the implementation of this myself. Which features would I like to have in my translation service? How can I accomplish them? I might end up with an alternative translation library. But it will not be as ‘feature-complete’ as the aforementioned libraries. Which is ultimately fine by me. I’m doing this for the experience.

If you’ve read some of my previous blogposts, you’ll know that I’m a big fan of Typescript. So naturally, I will be building this service with Typescript as well.

This will become a multi-part series, as there is too much information to drop into one post. I don’t have a number of parts in my head yet. I’ll figure it out as I go. For every part that I publish, the full source code will be made available in my GitHub repository.

All code is provided “as is”.

Part 1

In this first part, I will centralize all fixed texts in one location in the application. This way we can easily change text later on in the project without having to hunt down the text in html or Typescript code. This will also help reusing text like for instance standard error messages.

There will not yet be an actual translation option in this first part. I’m recreating the actual process of creating an application where in the earlier phase, translations were not on the table. Later on it became a requirement and that’s when I expanded from all text in one location and one language to one location and multiple languages.

Setting up an angular project

I’m assuming you all know how to set up an Angular project, so I’m not getting into the details of that. I used a simple company template which gives me the following structure:

In this project there is some text on the components html and in their controllers. Let me show you the home component:

Controller

private activate(): void {const self = this;//Test Toastsself.$timeout(() => {self.toastSvc.toastError('Hello World!')}, 0, true);self.$timeout(() => {self.toastSvc.toastInfo('Hello World!');}, 1000, true);self.$timeout(() => {self.toastSvc.toastSuccess('Hello World!');}, 2000, true);self.$timeout(() => {self.toastSvc.toastWarning('Hello World!');}, 3000, true);self.$timeout(() => {self.toastSvc.toastCustom({className: 'info',content: 'Hello World!
',});}, 4000, true);}

View (html)
```
Home Title
Hello World!
```

You can see that I used the same text Hello World! multiple times. If I want to change this now, it would require me to change each instance.

Centralizing text

I want to centralize all the text I put in my application into one location. Not one file, mind you, but one location. To accomplish that, I create a subfolder called resources inside the app folder. Inside this folder, I recreate the folder structure of the app.

I create a resource file for every component, for common error messages, … In short, anything you can think of that is plain text that needs to be shown somehow.

The resource file for my homecomponent looks like this:

module DeBiese.NgResources.Part1.Resources {export class Home {static title: string = 'Home Title';static helloWorld: string = 'Hello World!';}}

Using this in my controllers is straight forward. Just import a reference to the Home class in the Resources module.

import HomeMessages = DeBiese.NgResources.Part1.Resources.Home;

This gives me direct access to all the strings.

private activate(): void {const self = this;//Test Toastsself.$timeout(() => {self.toastSvc.toastError(HomeMessages.helloWorld)}, 0, true);self.$timeout(() => {self.toastSvc.toastInfo(HomeMessages.helloWorld);}, 1000, true);self.$timeout(() => {self.toastSvc.toastSuccess(HomeMessages.helloWorld);}, 2000, true);self.$timeout(() => {self.toastSvc.toastWarning(HomeMessages.helloWorld);}, 3000, true);self.$timeout(() => {self.toastSvc.toastCustom({className: 'info',content: `${HomeMessages.helloWorld}
`,});}, 4000, true);}

How do I use these strings in my html? When I import Home (the resource class) into my HomeController, I can use this in my controller because of how Typescript works. It knows that it will transpile the static string into a javascript string that’s accessible at runtime. But the import does not make this available on my view.

In order to make the static strings available in my view, I have to declare a public property on my controller and set it equal to my resource class.

homeResources: HomeMessages = HomeMessages;

Now I can access the strings in my html.

{{::vm.homeResources.title}}
{{::vm.homeResources.helloWorld}}

I’m using one-way binding, {{:: …}}, because I’m using static string values to bind to. And that’s it. I now have a consistent way of grouping all my text in one location and I know how to use this in my controllers, or any other code for that matter, and in the html.

Summary

Resource folder
- Recreate component structure
- Resource file for each component and common resources
Import where you want to use it in code
Declare variable in your controller and assign the resource class to it as value for use in your html view

Closing word

In this part I was looking for a way to centralize all my static text so that it would become easier to manage. In Part 2 I will expand on this to introduce translations.

The full code base of this little test project can be found on GitHub.

Feel free to comment down below!

Ruben Biesemans

Analyst Developer @ Spikes

How to – Authorization in AngularJS application with Windows Authentication

Ruben B — Tue, 20 Sep 2016 05:12:22 +0000

In my previous post I explained how to set up windows authentication in an Angular application.

In this post I will explain how to implement authorization in the application based on the authenticated user.

I’m starting this post with the code base of the previous post.

Extending the Web API

I’ll extend the API with a new model, AppUser, which will contain the user information that is necessary for Authorization in the application.

public class AppUser{public string DomainName { get; set; }public string Role { get; set; }}

Next I will change the WinAuthController. I’m returning an instance of the AppUser object when the user is successfully authenticated.

[HttpGet][Route("login")]public AppUser Authenticate(){Debug.Write($"AuthenticationType: {User.Identity.AuthenticationType}");Debug.Write($"IsAuthenticated: {User.Identity.IsAuthenticated}");Debug.Write($"Name: {User.Identity.Name}");if (User.Identity.IsAuthenticated){//return Ok(new AppUser { DomainName = User.Identity.Name, Role = "Admin" });return new AppUser { DomainName = "domain\\yourusername", Role = "Admin" };}else{throw new Exception("Not Authorized");}}

Typically, you would want to load the information from a database or something. To keep things simple, I’m just returning the domain name and a fixed role.

Extending the Angular application

In the Angular application, I’m moving the AuthenticationService into a separate Angular module, which I’m calling ‘debiese.security’. I’ll also add an AuthorizationService to the module. Again, to keep things simple, I also added a separate file for declaring the module. You shouldn’t do that in production code.

NOTE: Keep in mind that the Angular module should exist before the services are added to it. So the order of loading them in the application matters!

My security module:

As I said, the securityModule is solely for declaring the debiese.security Angular module.

angular.module('debiese.security', []);

Both the AuthenticationService and the AuthorizationService are added to this module.

angular.module('debiese.security').service(S.AuthenticationService.id, S.AuthenticationService);.service(S.AuthorizationService.id, S.AuthorizationService);

I’m creating this separate module because I want to access the Authentication- and Authorization Services in the application runtime (app.run).

AuthenticationService

Let’s have a look at the changes in the AuthenticationService first.

export interface IAuthenticationService {authenticatingPromise: ng.IPromise;authenticate: (forceAuthentication?: boolean) => ng.IPromise;getUser: () => M.IAppUser;isAuthenticated: () => boolean;isAuthenticating: () => boolean;}

A lot has changed compared to my previous sample.

getUser
Returns an AppUser object when the authentication was successful. Otherwise it returns null.
```
getUser(): M.IAppUser {const self = this;return self._identity;}
```

isAuthenticted
Returns true when authentication was successful. Otherwise it returns false.
```
isAuthenticated(): boolean {const self = this;return self._identity != null;}
```
isAuthenticating
Returns true when the authentication is in progress. Otherwise it returns false.
```
isAuthenticating(): boolean {const self = this;return self._isAuthenticating;}
```

authenticate
This is where it all happens.The most important part is calling the WinAuthController on the Web API to authenticate. But I also want to provide some information on the AuthenticationService to know if the user is already authenticated.If for some reason the authenticate method is called a second time, we can immediately provide the result without calling the Web API again. Unless of course I want to force a call to the Web API by providing the forceAuthentication parameter.When I initiate the authentication by calling the Web API, the _isAuthenticating variable is set to true. Also the variable authenticatingPromise is initiated. I do this so that I can call isAuthenticating and if that returns true, I can write code to execute when the authenticatingPromise resolves.

authenticate(forceAuthentication?: boolean): ng.IPromise {const self = this;let defer = Q.defer();if ((!self.isAuthenticated && !self._hasAuthenticated) || (forceAuthentication != null && forceAuthentication === true)) {let serviceUrl: string = `${C.Configuration.AppConfig.serviceBaseUrl}auth/login`;self._hasAuthenticated = false;self._isAuthenticating = true;//Initiate promise that will resolve when authentication process is complete.//This is usefull when authorization is being checked when the authentication is not yet complete.let authDefer = Q.defer();self.authenticatingPromise = authDefer.promise;self.$http.get(serviceUrl).success((data, status, headers, config) => {self._identity = data as M.IAppUser;defer.resolve(true);}).error((data, status, headers, config) => {self.logSvc.log(data);defer.reject(new M.RejectMessage({ Message: data }));}).finally(() => {self._hasAuthenticated = true;self._isAuthenticating = false;//Let any code waiting for the authentication to finish know that authentication finished!authDefer.resolve();});} else {defer.resolve(self.isAuthenticated());}return defer.promise;}

AuthorizationService

export interface IAuthorizationService {isAuthorized: (requiredRole: string) => boolean;}

I’m implementing a fairly easy isAuthorized method in which we check if the authenticated user has a specific role. This can be as complicated as you like, but in this example, this simple check will suffice.

UI-Router configuration

With the Authentication- and Authorization services in place, I can start using this to add authorization on the router configuration. I’ll be using the data object on the state configuration to configure which states require the user to be authenticated and which role a user needs to have to be able to access a state.

I created the StateSecurity object to keep things together.

export class StateSecurity implements IStateSecurity {LoginRequired: boolean;Role: string;constructor(obj?: IStateSecurity) {if (obj != null) {this.LoginRequired = obj.LoginRequired;this.Role = obj.Role;}}}

The states in the application:

$stateProvider.state('home', {url: '/home',templateUrl: '/app/components/home/homeView.html',controller: DeBiese.Authorization.NG.Controllers.HomeController.id,controllerAs: 'vm',data: {security: new M.StateSecurity({LoginRequired: true,Role: 'Admin'})}}).state('help', {url: '/help',templateUrl: '/app/components/help/helpView.html',controller: DeBiese.Authorization.NG.Controllers.HelpController.id,controllerAs: 'vm',data: {security: new M.StateSecurity({LoginRequired: true,Role: 'User'})}}).state('loading', {url: '/loading',templateUrl: '/app/components/loading/loadingView.html'}).state('unauth', {url: '/unauth',templateUrl: '/app/components/authorization/notAuthorizedView.html',controller: DeBiese.Authorization.NG.Controllers.NotAuthorizedController.id,controllerAs: 'vm'});

Two states require the user to be authenticated, the other 2 don’t. Obviously the Not Authorized state should not require the user to be authenticated. The loading state will be discussed later on in the post.

Implementing the authorization

Adding the StateSecurity objects to the state doesn’t do anything in itself. I need to enforce usage of that information myself. The way to do this, is by intercepting the stateChangeStart event that is broadcasted on the $rootScope by the ui-router.

$rootScope.$on('$stateChangeStart',(event: any, toState: angular.ui.IState, toParams: angular.ui.IStateParamsService, fromState: angular.ui.IState, fromParams: angular.ui.IStateParamsService) => {//Implementation here});

When a state change is initiated I can check the data object on the state, and if a StateSecurity object is available I’ll inspect it and if necessary use it for authorization. If not, the state change can continue without performing additional actions on it.

if (toState.data != null && toState.data.security != null) {//Implementation here}

If StateSecurity is configured on a state, but during the state change the authentication process is still running (I provided the isAuthenticating method for this), I don’t want the state change to take place. So I prevent the default action (the change of state) and write code to run when the authenticatingPromise on the AuthenticationService resolves. I simply re-initiate the state change with the same parameters. In the meantime, however, I need to make sure that something is loaded. That’s why I provided the loading state.

//If authentication is still in progress, prevent navigation and retry when authentication is completeif (authenticationSvc.isAuthenticating()) {//Navigate to unprotected route for the time being (prevents infinite digest loop)//Might cause slight flicker on screen when authentication is quick.$state.go('loading');event.preventDefault();//Stave navigation when authentication is finishedauthenticationSvc.authenticatingPromise.then(() => {$state.go(toState, toParams);});}

Let me explain that in a bit more detail. If I prevent the default action on a state change without initiating a new state transition, the application will then try to load the default route. The default route will trigger a state change to the home state. This state has a StateSecurity object and as we already know, the AuthenticationService is still authenticating. So this would trigger an infinite digest loop. The way around this behavior is to initiate a state change myself instead of just preventing the original state change and make the transition to a state that has no StateSecurity object. When the authenticatingPromise resolves, the original state change is initiated.

This leaves the situation where a state change is initiated, a StateSecurity configuration is in place and the authentication process is completed. I check if a login is required and if so whether or not the logged in user has the necessary role to access the desired state. If not, a NotAuthorized state is loaded.

//If authentication is still in progress, prevent navigation and retry when authentication is completeif (authenticationSvc.isAuthenticating()) {//...}else {let security: M.IStateSecurity = toState.data.security as M.IStateSecurity;if (security.LoginRequired && !authorizationSvc.isAuthorized(security.Role)) {$state.go('unauth');event.preventDefault();}}

In the sample application, I return the Admin role for every user. This means that every user is allowed to access the Home state, but not the Help state which requires a role with the name User.

Summary

Security module
- AuthenticationService
- AuthorizationService
UI-Router configuration
- StateSecurity configuration
App.run
- Initiate authentication
- Intercept stateChangeStart for authorization

Closing word

I hope the provided information gives you some insight into the authorization process. Keep in mind that this is all done in Typescript (javascript) and can be easily manipulated by a tech-savvy user. This means that on the Web API, we also have to implement authorization on actions that can be called from pages I configured to need authorization in the application. It’s out of scope for this blog post, but you should not overlook this when building a real world application.

The full code base of this little test project can be found on GitHub.

Feel free to comment down below!

Ruben Biesemans

Analyst Developer @ Spikes

How to implement Windows Authentication in an AngularJS application with a stand-alone Web API

Ruben B — Thu, 08 Sep 2016 17:04:24 +0000

UPDATE:

There’s an up-to-date version explaining how to do this in Angular 4.3.1 and higher which can be found here.
The new post refers to this post for setting up the Web API and continues with the Angular 4.3.1 (and higher) set up.

How hard can this be, really? Sounds simple enough and once you figure it out, it really is. But as it took me some research on various small issues along the road, I thought, why not bring all the pieces of the puzzle together. And so here we are.

In this post, I am going to build a small sample application from the ground up. I will focus on the key points of getting everything set up correctly.

Let’s give this post some clear boundaries:

Angular JS web project
Web API project
Windows Authentication

Creating the solution

First, we’ll need a Web API project for the backend. We only want the Web API part, so we pick the Empty template and check Web API. As you can see, we cannot change the authentication at this point. We’ll get to that later on.

Next, we’ll create the AngularJS application. I’m using a very basic company template here to avoid having to setup too much repetitive stuff. Any web project where you add Angular into will do.

The solution will look something like this:

Configure IIS Express

At this point we are ready to configure our IIS Express to use Windows Authentication. At the moment I’m using Visual Studio 2015, which means I have a (hidden) .vs-folder in my solution folder.

Drilling down into the folder we come across a config folder which contains an application.config file. We can alter this file for solely the solution which we are working on.

Let’s set the authentication inside this application.config file as follows:

Setting up our Web API

For the interest of this post, I created 2 Controllers in the Web API:

WinAuthController
This can be used to retrieve some additional information for the logged in user using some other resource such as an SQL database.
DataController
Our controller that will be handling our very important data.

Add both controllers to the Web API project as empty Web API 2 controllers.

I also added a model to my Web API project ‘PostData’ which will hold our data.
We now have this:

The implementation:

PostData

public class PostData{public int Id { get; set; }public string Name { get; set; }public bool IsTrue { get; set; }public DateTime CreatedOn { get; set; }public override string ToString(){return $"PostData with [Id: {this.Id.ToString()}] - [Name: {this.Name}] - [IsTrue: {this.IsTrue.ToString()}] - [CreatedOn: {this.CreatedOn.ToString("dd/MM/yyy")}].";}}

WinAuthController

[Authorize][RoutePrefix("auth")]public class WinAuthController : ApiController{[HttpGet][Route("getuser")]public IHttpActionResult GetUser(){Debug.Write($"AuthenticationType: {User.Identity.AuthenticationType}");Debug.Write($"IsAuthenticated: {User.Identity.IsAuthenticated}");Debug.Write($"Name: {User.Identity.Name}");if (User.Identity.IsAuthenticated){//return Ok($"Authenticated: {User.Identity.Name}");return Ok("Authenticated: yourdomain\\yourUserName");}else{return BadRequest("Not authenticated");}}}

DataController

[Authorize][RoutePrefix("data")]public class DataController : ApiController{[HttpPost][Route("save")]public IHttpActionResult Save(PostData data){return Ok(data.ToString());}}

As we are implementing the Web API separate from the Angular application, they are both running on different ports in IIS Express. We’ll have to setup CORS (Cross Origin-Requests).

Add the package to the Web API project through NuGet:

Let’s configure the Web API for CORS.

var cors = new EnableCorsAttribute("*", "*", "*");

Setting it up like this opens up the Web API for every origin, header and method. But this doesn’t suit our needs. Because we want to use Windows Authentication, we have to configure CORS in such a way that it knows we are passing credentials. This means changing the EnableCorsAttribute to this:

var cors = new EnableCorsAttribute("http://localhost:30033", "*", "*") { SupportsCredentials = true };

Setting SupportsCredentials to true tells our Web API that credentials can be passed in the request. It also requires us to change the origins configuration to actually say which origin(s) are allowed to call our Web API. You can’t use SupportsCredentials as true along with * for the origins.

We are going to call the Web API from our Angular application, so I’m going to set up the Web API to return json instead of XML.

This is done like so:

config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/html"));

All this configuration is done in the WebApiConfig file (in the App_Start) folder of the project.

The complete file now looks like this.

Just one change in the web.config file and we are done in the Web API. Set the authentication mode to Windows.

Setting up our Angular application

I’m using Angular 1.5.7. without using the component router. Also, I started using Typescript for Angular projects a while back now. If you don’t use Typescript (yet), I advise you to reconsider. I won’t go into the details about why you should use Typescript (in my opinion), but do give it a shot!

So the template I used gave me a basic functional Angular application with a Home and a Help page. Both of which can be accessed through a navigation bar.

We’ll start by adding 2 services to the application. One service per controller in our WebAPI. So we have this:

authenticationService

getUser(): ng.IPromise {const self = this;self.logSvc.log('Calling getUser');let defer = Q.defer();let serviceUrl: string = `${C.Configuration.AppConfig.serviceBaseUrl}auth/getuser`;self.$http.get(serviceUrl).success((data, status, headers, config) => {defer.resolve(data as string);}).error((data, status, headers, config) => {self.logSvc.log(data);defer.reject(new M.RejectMessage({ Message: data }));});return defer.promise;}

dataService

save(data: M.IPostDataModel): ng.IPromise {const self = this;self.logSvc.log('Calling getUser');let defer = Q.defer();let serviceUrl: string = `${C.Configuration.AppConfig.serviceBaseUrl}data/save`;self.$http.post(serviceUrl, data).success((data, status, headers, config) => {defer.resolve(data as string);}).error((data, status, headers, config) => {self.logSvc.log(data);defer.reject(new M.RejectMessage({ Message: data }));});return defer.promise;}

As in the Web API, each of the services has 1 method.

Next we’ll add a model to our app which will be the client side representation of our server side PostData object.

module DeBiese.WinAuth.NG.Models {export interface IPostDataModel {Id: number;Name: string;IsTrue: boolean;CreatedOn: Date;}export class PostDataModel implements IPostDataModel {public Id: number;public Name: string;public IsTrue: boolean;public CreatedOn: Date;constructor(obj?: IPostDataModel) {if (obj != null) {this.Id = obj.Id;this.Name = obj.Name;this.IsTrue = obj.IsTrue;this.CreatedOn = obj.CreatedOn;}}}}

The home page will be used for our test implementation, so we inject our 2 services into the homeController and add 2 methods for calling those services.

testAuthentication(): void {const self = this;self.authSvc.getUser().then((rslt) => {self.toastSvc.toastSuccess(rslt);}).catch((err) => {self.logSvc.log(err);self.toastSvc.toastError('An unexpected error occurred.');});}testPostData(): void {const self = this;self.dataSvc.save(new M.PostDataModel({ Id: 1, Name: 'DeBiese', IsTrue: false, CreatedOn: new Date() })).then((rslt) => {self.toastSvc.toastSuccess(rslt);}).catch((err) => {self.logSvc.log(err);self.toastSvc.toastError('An unexpected error occurred.');});}

We’ll add 2 buttons to our homeView which will invoke those methods.

Like we did with the Web API, we’ll have to tell Angular to pass credentials when doing http requests. We do this by injecting the $httpProvider into our configuration class for the angular app and setting withCredentials to true.

$httpProvider.defaults.withCredentials = true;

And we are done (for now)!

Testing the application

Let’s fire up both the Web API and the Angular application.

Our two buttons are in place. So let’s click the Authentication button.
The result on the page is as follows:

Good, a http get is working. Now for the post. Let’s click Post Data.
And the result:

Woops.

Opening up dev tools, we see this error message:

What’s happening here? It’s saying that the response to the preflight request doesn’t pass the access control check.

For those of you that are not familiar with a preflight request, you can find some more information here.

The reason our little application is sending a preflight request, is that we are sending data as application/json which is not one of the possibilities for using a http post without sending a preflight request.

If you are like me and you get that error message, you will start googling for that preflight request and why the response does not pass the check. Which would throw you off the right path right away. That’s because further on in the error message, you’ll find the actual issue. Which is: The response had HTTP status code 401.

So our preflight request couldn’t get authenticated. This is perfectly normal because a preflight request DOES NOT send authentication information and we configured our Web API to not allow anonymous authentication.

While setting up the Web API, we decorated our controllers with the Authorize attribute thus ensuring that only authorized requests can pass through. This means that we can once again modify our application.config file to allow anonymousAuthentication.

In addition, you should also modify your web.config file in the Web API project to allow anonymous users. This is because otherwise visual studio adds a section to the application.config file to overwrite the anonymousAuthentication setting we just set to true.

This setting will ensure that preflight requests get handled correctly by our Web API without responding with an HTTP 401.

And there you have it, pushing the Post Data button again will return the actual expected result from the controller.

An interesting side note, which I find worth mentioning, is that Internet Explorer (11) does not respond with the preflight request error when anonymousAuthentication is disabled.

Summary

application.config

Web API

Add CORS

Configure CORS

var cors = new EnableCorsAttribute("http://localhost:30033", "*", "*") { SupportsCredentials = true };

Configure for json instead of XML

config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/html"));

Web.config settings
```
  
```

Angular app
- Configure $httpProvider (withCredentials)
```
$httpProvider.defaults.withCredentials = true;
```

Closing word

I hope this post provides you some insight into the matter. Getting this to work correctly took me a while. Looking back, it was mostly due to the preflight request error which caught my attention and threw me off. I was too focused on the start of the message that I at first missed the HTTP 401 response.

The full code base of this little test project can be found on GitHub.

Feel free to comment down below!