With the new HttpClient introduced in Angular 4.3.1, I think it’s a good moment to write a little update.

I’m following the same setup as the previous post:

• Angular project
• Web Api project
• Windows Authentication

Let’s get started.

Web Api

Little has changed for the Web Api part. The short version is:

• application.config

  <authentication><anonymousAuthentication enabled="true" userName="" /><basicAuthentication enabled="false" /><clientCertificateMappingAuthentication enabled="false" /><digestAuthentication enabled="false" /><iisClientCertificateMappingAuthentication enabled="false"></iisClientCertificateMappingAuthentication><windowsAuthentication enabled="true"><providers><add value="Negotiate" /><add value="NTLM" /></providers></windowsAuthentication></authentication>

• 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

    <authentication mode="Windows"/><authorization>  <allow users="?"/></authorization>

You can find the in-detail version here.

Some points of interest in the Web API setup:

• In the CORS configuration we need to set which url’s are can contact our api. I’m developing an angular project with the angular-cli. The default is http://localhost:4200

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

• I’ve noticed that while setting up a project, as described in my previous post, works as expected if you start from scratch. Starting from the github repo of my sample, sometimes you keep getting a 401 unauthorized on the post request.
  If that’s the case, you can easily solve this by selecting the web api project in visual studio and open up the properties. Make sure to set Anonymous Authentication to Enabled.
  

Setting up our Angular application

I’m using the angular-cli. If you don’t know how to use it, check out their getting started information before continuing.

After setting up the application, we include the new HttpClientModule in the app.module:

import { HttpClientModule } from '@angular/common/http';@NgModule({  declarations: [AppComponent  ],  imports: [BrowserModule,HttpClientModule  ],  providers: [  ],  bootstrap: [AppComponent]})export class AppModule { }

Note: take special note of the fact that I’m using the new http import from @angular/common/http and not the old(er) one from @angular/http which still exists and works as before. I want to make use of newer functionality so I’m going for the new http implementation.

Next, add 2 services to the application.

• AuthenticationService

  getUser(): Observable<string> {console.log('Calling getUser');let serviceUrl: string = `${environment.serviceBaseUrl}auth/getuser`;return this.http.get(serviceUrl, {responseType: 'text'})  .map((rslt: string) =>{return rslt;  });  }

• DataServices

  save(data: models.IPostDataModel): Observable<string> {console.log('Calling getUser');let serviceUrl: string = `${environment.serviceBaseUrl}data/save`;return this.http.post(serviceUrl, data, {responseType: 'text'})  .map((rslt: string) => {return rslt;  });  }

Note: the new http client uses json by default. And tries to parse what is returned by a request as json. In our sample web api we return a string, so we need to specify another responseType. Which in our case will be text. More about this can be found here.

Import and provide those services in the app module :

import * as svcs from './services/';providers: [svcs.AuthenticationServiceService,svcs.DataServiceService],

Create the necessary data model for our server side PostData object.

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) {Object.assign(this, obj);}}}

 
I’m using the AppComponent for demonstrating the windows authentication by adding 2 buttons to it.

<div style="text-align:center">  <div class="row"><div class="col-lg-12"><button type="button" (click)="testAuthentication()">Authentication</button><pre style="border:solid 1px;min-height:21px;" [ngClass]="[authBack]">{{authRslt}}</pre></div><div class="col-lg-12"><button type="button" (click)="testPostData()">Post Data</button><pre style="border:solid 1px;min-height:21px;" [ngClass]="[postBack]">{{postRslt}}</pre></div>  </div></div>

And of course the functions that will be executed when clicking the buttons.

  testAuthentication(): void {this.authSvc.getUser()  .subscribe(r => {this.authRslt = r; this.authBack = 'success';},e => {console.log(e); this.authBack = 'error';}  );  }  testPostData(): void {this.dataSvc.save(new models.PostDataModel({Id: 1, Name: 'DeBiese', IsTrue: false, CreatedOn: new Date()}))  .subscribe(r => {this.postRslt = r; this.postBack = 'success';},e => {console.log(e); this.postBack = 'error';}  );  }

HttpInterceptor

In the new http client module, intercepting a request and/or response is very easy. Writing an interceptor is like writing an angular service that implements the HttpInterceptor interface.

An example of an interceptor is the following:

import { Injectable } from '@angular/core';import {  HttpRequest,  HttpHandler,  HttpInterceptor,  HttpEvent} from '@angular/common/http';import { Observable } from 'rxjs/Observable';@Injectable()export class WinAuthInterceptor implements HttpInterceptor{  constructor(){}  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {return next.handle(req);  }}

This interceptor is doing nothing now. It intercepts a request and passes it on without change.

In our case, we want to make sure that every request adds the current user’s windows credentials. The intercept method changes to this:

  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {req = req.clone({  withCredentials: true});return next.handle(req);  }

The request (response) object needs to be immutable, so we need to clone the original request before we return it. We set the withCredentials parameter to true so that every outgoing request adds those credentials.

Lastly, we need to make sure that this interceptor is being used. So we need to register it in the app module.

  providers: [{  provide: HTTP_INTERCEPTORS,  useClass: int.WinAuthInterceptor,  multi: true},svcs.AuthenticationServiceService,svcs.DataServiceService  ],

Testing the application

Let’s fire up both the Web API and the angular application:

After clicking the buttons:

Both requests are successful, meaning the windows authentication is working the way we want it to work.

Conclusion

Using windows authentication with the new HttpClientModule in Angular 4.3.1 (or higher) is fairly easy. Just write an interceptor and make sure it is being used by providing it in your app module.

I hope this post provides you with enough information to set this up yourself.

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

Feel free to comment below!

• 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.

<nav>  <a [routerLink]="['/']">Home</a></nav><router-outlet></router-outlet>

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.

<router-outlet></router-outlet>

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 <a [routerLink]="['/login']">here</a> to log back in.

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

<nav>  <a [routerLink]="['/']">Home</a>  <a [routerLink]="['/logout']">Logout</a></nav><router-outlet></router-outlet>

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.

<nav>  <a [routerLink]="['/']">Home</a>  <a [routerLink]="['/employee']">Employees</a>  <a [routerLink]="['/logout']">Logout</a></nav><router-outlet></router-outlet>

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<Array<IEmployee>> {return this.http.get(`${environment.apiUrl}Employee`)  .map(response => {const tmp = <IEmployee[]>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<IEmployee> = [];  constructor(private empSvc: EmployeeService  ) { }  ngOnInit() {this.empSvc.getEmployees().subscribe(  rslt => this.employeeList = rslt,  error => console.log(error));  }}

<h3>Employees</h3><table><thead><tr><th>Id</th><th>Name</th><th>Function</th></tr></thead><tbody><tr *ngFor="let emp of employeeList"><td>{{emp.id}}</td><td>{{emp.name}}</td><td>{{emp.function}}</td></tr></tbody></table>

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.

We’ll cover these topics:

• Sharing
• Sync
• Storage
• Device access
• Compliance

Sharing

In the sharing section, you control access for internal and external users. Both can be managed separately and sharing settings can be set to include or exclude anonymous links or external users.

A welcome change is to limit the domains that are accepted or blocked for sharing access.

Sync

The admin page allows admins to control what machines can sync company data or to block syncing of specific file types.

Multiple domains can be added as an Allowed domain to sync data. An admin can, together with the option to block syncing of specific file types create very simple rules with a high return on data management.

Microsoft also provides a link that provides solutions to the most common OneDrive problems.

Storage

Next on the options list: storage. By default, users get the full amount of storage. Since here are plans with 5Tb, this can be a bad idea.

The managers will receive a notice when a deleted user’s files will be deleted, the admin page lets you set the period after which data will be deleted.

Device access

Device access options allow a setup of a granular access to protect the user his data. IP whitelisting and modern authentication can be enforced. But the creation of a mobile application management policy is a welcome feature. Note: Intune policies will take precedence for the selected users and will not be enforced on personal accounts.

You even can manage the offline behaviour of the client.

Compliance

If the organisation has legal, regulatory or technical standards or if there is the need to identify or and protect sensitive information, this can be done in the Security and Compliance section.

Next to auditing, DLP policies can be created. Data loss prevention (DLP) policies help to identify and protect your organisation’s sensitive information. For example, you can set up policies to help make sure the information in email and docs isn’t shared with the wrong people.

In the alert section, a lot of OneDrive actions are added so notifications can be generated and sent out.

Final notes

Microsoft added some very nice features what makes OneDrive more business friendly by enabling admins to control the way OneDrive and the company data behave. Users were able to sync the data to almost any device and it would stay accessible even if the account is removed. I surely hope that this is only the first step towards central OneDrive management.

In this blogpost I will show you how you can access your SharePoint data in a secure way, without using the AppOnly token. I will not even create a SharePoint add-in.

The three main components that will be used in this demo are:
– Azure AD application
– Azure web app to host your web service
– SharePoint online

Basicaly this means you will need to be global administrator on Azure to complete all of the steps.

Build your Web API in Visual Studio

Create a Visual Studio project

Open Visual Studio and create a new ASP.NET Web Application

Create an empty project. I opted to add folders and references for Web API and to host the web app in the cloud.

Because I selected to host the app in the cloud in the previous step, I can create the app service that will host the API from the same wizard.

Click Create.

Add NuGet packages

We will start to add some NuGet packages to the backend web project. Click Tools > NuGet Package Manager > Package Manager Console. Install the following packages:

Install-Package Microsoft.AspNet.WebApiInstall-Package Microsoft.AspNet.WebApi.OwinInstall-Package Microsoft.Owin.Host.SystemWebInstall-Package Microsoft.Owin.Security.ActiveDirectoryInstall-Package Microsoft.IdentityModel.Clients.ActiveDirectory -Version 2.15.204151539Install-Package SharePointPnPCoreOnline

Add Owin Startup Class

We will start by telling the Owin Framework what class is responsible for the Owin initialization.
Add a new item of type OWIN Startup class to the backend web project.

Add the following code snippet to the Startup class

[assembly: OwinStartup(typeof(Spikes.SecureWebAPIWeb.Startup))]namespace Spikes.OAuthWebAPI{public partial class Startup{public void Configuration(IAppBuilder app){ConfigureAuth(app);HttpConfiguration config = new HttpConfiguration();WebApiConfig.Register(config);app.UseWebApi(config);var jsonFormatter = config.Formatters.OfType<JsonMediaTypeFormatter>().First();jsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();}public void ConfigureAuth(IAppBuilder app){app.UseWindowsAzureActiveDirectoryBearerAuthentication(new WindowsAzureActiveDirectoryBearerAuthenticationOptions{Tenant = ConfigurationManager.AppSettings["ida:Tenant"],TokenValidationParameters = new TokenValidationParameters{ValidAudience = ConfigurationManager.AppSettings["ida:Audience"]},});}}}

Update WebApiConfig Class

Open the class WebApiConfig located in the App_Start folder and update with the folowing code.

public static class WebApiConfig{public static void Register(HttpConfiguration config){config.MapHttpAttributeRoutes();config.EnableCors();config.Routes.MapHttpRoute(name: "DefaultApi",routeTemplate: "api/{controller}/{id}",defaults: new { id = RouteParameter.Optional });config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/html"));}}

Add a Controller to Handle Requests

Create a new Folder named Controllers. Add a new Web API 2 Controller.

Give it a name.

Add the following code to it. The Authorize attribute will make sure that only authorized calls are allowed to access the controller. The GetSharePointAccessToken will get a new token to access SharePoint Online and get the sites’s web title.

[Authorize][RoutePrefix("api/v1/oauth")]public class OAuthController : ApiController{[HttpGet][Route("getwebtitle")]public string GetWebTitle(string sharePointUrl){string accessToken = GetSharePointAccessToken(sharePointUrl, this.Request.Headers.Authorization.Parameter);using (var context = TokenHelper.GetClientContextWithAccessToken(sharePointUrl, accessToken)){Web web = context.Web;context.Load(web);context.ExecuteQuery();return web.Title;}}internal static string GetSharePointAccessToken(string url, string accessToken){string clientID = ConfigurationManager.AppSettings["ida:ClientID"];string clientSecret = ConfigurationManager.AppSettings["ida:ClientSecret"];var appCred = new ClientCredential(clientID, clientSecret);var authContext = new AuthenticationContext("https://login.windows.net/common");AuthenticationResult authResult = authContext.AcquireToken(new Uri(url).GetLeftPart(UriPartial.Authority), appCred, new UserAssertion(accessToken));return authResult.AccessToken;}}

Configure your Azure web app

Log on to your Azure portal and go to the web application you have created earlier. First of all, we will make sure that this web app can only be accessed by athenticated users.

Authentication / Authorization

Open  your web app and go to Authentication / Authorizatio settings. Turn on App Service Authentication and select Azure AD as authentication provider.

Choose Express settings > Create New AD App.

After you have clicked Ok, you should save your settings! An Azure AD Application will be created in the background.

CORS settings

To make sure we can access our web API, we also have to update the CORS settings. More information about CORS can be found here. I have allowed all origins here, but of course in real life, you also want to restrict that.

Configure your Azure AD Application

The Azure AD application has been created in the background for us, but still we need to update some settings and grab some information from it to make our solution work.

OAuth 2.0 Authorization Code Grant Flow

Your first step is to generate a client secret (key) in the configuration page of your Azure AD application. Be aware that once your client secret is generated, you will not be able to see it again – so store it safely once you get it. We will need this later.

OAuth 2.0 Implicit Grant Flow

If you’re building a SPA web app you may be in need of the implicit grant flow, as you’ll perform most of your computing on the client-side. Before you can use the implicit grant flow with your Azure AD application – you will need to enable it in your Azure AD application. Go to the manifest of your application and update the setting oauth2AllowImplicitFlow from false to true.

Reply Urls

We also need to update the Reply URLs. Add the url(s) from where you will call the web API. If the location is not listed here, you will get an error when trying to access it. You can also see this as some kind of security.

Permissions

Here we will set the permissions our application will need. If you want to act on behalf of a user, you should pick delegated permissions. In this example we will as the Office 365 SharePoint Online API.

Properties

Now everything is set up, we will need to grab some parameters. We will need those later add them to the web.config of our web application and to our javascript that will call the web API.

• TenantId: you can find in the endpoints section. Take any of the endpoints urls. The guid in there corresponds to your tenant ID
• ClientId: the Application ID, found in the properties page of your application
• Audience: the App ID URI, found in the properties page of your application

Consent

One last step to start using our API, is provide and admin consent to our application. Update the following url with the parameters of your own application and paste it in your browser.

https://login.microsoftonline.com//oauth2/authorize?response_type=code&client_id=&redirect_uri=&prompt=admin_consent

Log in with your admin account. You will be redirected to a content page which provides you an overview of permissions you have granted to your application. Click Accept.

Note that every time, you make changes to the permissions, you need to regrant the application consent.

Configure & publish the web app

Now that everything is set up, we Open the web.config of the web app and add the following parameters:

We are ready to publish our web app to Azure!

Let’s test!

To test the web API, I have created a simple HTML page with a button that will call the web API. The result is printed to the console.

I have added a content editor web part to a SharePoint site in my tenant and referenced this html file.

<!DOCTYPE html><html><body><h1>OAuth Web API test page</h1><input type="button" id="button" name="button" value="Click me" /><script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script><script src="https://secure.aadcdn.microsoftonline-p.com/lib/1.0.0/js/adal.min.js"></script><script type="text/javascript">  $("#button").click(function(){var webTitle = GetTitle();  });  "use strict";  window.config = {instance: 'https://login.microsoftonline.com/',tenant: '' // Update with your tenant ID,clientId: '' // Update with your application ID,postLogoutRedirectUri: window.location.origin,endpoints: {   endPointApiUri: 'https://spikesoauthwebapi.azurewebsites.net' // Update with your azure web url},cacheLocation: 'localStorage' // enable this for IE, as sessionStorage does not work for localhost.  };  function GetTitle() {var authContext = new AuthenticationContext(config);// Check For & Handle Redirect From AAD After Loginvar isCallback = authContext.isCallback(window.location.hash);authContext.handleWindowCallback();if (isCallback && !authContext.getLoginError()) {  window.location = authContext._getItem(authContext.CONSTANTS.STORAGE.LOGIN_REQUEST);}// If not logged in force loginvar user = authContext.getCachedUser();if (user) {  // Logged in already}else {  // NOTE: you may want to render the page for anonymous users and render  // a login button which runs the login function upon click.  authContext.login();}authContext.acquireToken(authContext.config.clientId, function (error, token) {  if (error || !token) {  console.log("ADAL error occurred: " + error);  return;  }  console.log("ADAL token: " + token);  var uri = config.endpoints.endPointApiUri +  "/api/v1/oauth/getwebtitle";  $.ajax({  type: "GET",  url: uri,  data: {  "sharePointUrl": "" // Update with a SharePoint Url in your tenant  },  headers: {  'Accept': 'application/json',  "Authorization": "Bearer " + token  }  }).done(function (response) {console.log("Success.");  console.log(response);  return response;  }).fail(function () {  console.log("Failed.");  });});  }</script></body></html>

Check the browser console – you will find the token and the name of the site!

Now what will happen if we open the same html file from a location that is not defined in our Azure AD application? Outside the SharePoint context?

You will be redirected to the Microsoft online sign in page where you are asked for your credentials. So far, so good.

But you will get an error message because the reply address is not a valid URL..

Sources:

The following source code on PnP was very big help while testing Azure Active Directory Authentication and writing this blog: https://github.com/SharePoint/PnP/tree/master/Samples/AzureAD.WebAPI.SPOnline

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

• Part 1
• Part 2

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<C.KeyValuePair<string, string>> = [{ key: 'title', value: 'Home Title' },{ key: 'helloWorld', value: 'Hello World!' }];let Translations_nl: Array<C.KeyValuePair<string, string>> = [{ key: 'title', value: 'Home Titel' },{ key: 'helloWorld', value: 'Hallo wereld!' }];self.languageDictionary = new C.Dictionary<string, C.Dictionary<string, string>>([{ 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<string>;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<IResourceFile>;preferredLanguage: string = 'en';constructor() {this.$resourceFiles = [];}addResourceFile(file: IResourceFile): void {const self = this;self.$resourceFiles.push(file);}getResourceFiles(): Array<IResourceFile>{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<string> = ['$http'];private $resourceDictionary: Dictionary<string, Dictionary<string, string>> = null;private $dictionary: Dictionary<string, string> = null;private $loadedResourceFiles: Dictionary<string, IResourceFile> = null;constructor(private $http: ng.IHttpService) {this.$resourceDictionary = new Dictionary<string, Dictionary<string, string>>();this.$dictionary = new Dictionary<string, string>();this.$loadedResourceFiles = new Dictionary<string, IResourceFile>();}private loadResourceFile(resourceFile: IResourceFile): ng.IPromise<boolean> {const self = this; let defer = Q.defer();let loadPromises: Array<any> = [];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<boolean> {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<string, string> = new Dictionary(data as Array<KeyValuePair<string, string>>);let tmpDictionary: Dictionary<string, string> = null;if (self.$resourceDictionary.containsKey(languageToLoad)) {tmpDictionary = self.$resourceDictionary.getValue(languageToLoad);}else {tmpDictionary = new Dictionary<string, string>();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<any> = [];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!

We found out that there are few solutions available for displaying the results as a list view, filtering and document preview. But most of them do one or the other while we needed all of them combined. So we decided to build it ourselves. The files we started building from can be found at the following GitHub link, these will lay the groundwork for displaying the results in list format. The folder will contain several files, but we are only going to use Control_List_Table.html and Item.List.Item.html.

To start off, we wanted to be sure the customer knew that we would not implement every functionality of a list, this would take us to far.

Adding the display template

The files you downloaded can be uploaded in the Content Web Parts folder under Display Templates folder. The exact upload location of the display templates does not matter, as long as it is in the Display Templates folder under the masterpage gallery. The meta data fields which show up when the files are uploading, can be ignored.

As seen in the screenshot above, on the right side, SharePoint will automatically generate one JavaScript file for each item uploaded. When you modify the html files, make sure to publish the files. This can be done by right clicking on the items you just uploaded and clicking on ‘Publish’. Else you might find that not everyone can see your changes.

Before the display template can be configured, the search managed properties that will be used in the display template must be configured correctly. The display template has sorting functionality, in order for this to work, the sorting option on the managed properties that need to be sortable must be selected.

Modifications

As you can see in the screenshot, we added a document preview to the list for every item. The document preview will show up if you click on the ellipsis of an item.  The buttons you see when the preview is open are also added and the information displayed (like author) is configurable in the web part which we will discuss further in this blog.

Another thing we added are the sorting options hidden behind that little triangle next to the column name, as in a list. This is done as following: 

One of the downsides of trying to copy something, is that you can’t copy it for 100%. One of those things is that you can’t sort very well on for example a date. In the search results the results are not seen as type they are, but just as text. So if you want to sort a date column, it will not work properly because it is not seen as a date, but as a text type.

Filtering can be done by connecting a search box web part to the content search web part. This will filter the search results.

The snippet below will render the menu when clicking on the small triangle in the column header.

spikes.Header.Menu = function() {return {showMenu: function(element) {var headerElement = element.parentElement.parentElement;var menuElements = headerElement.getElementsByClassName("ms-core-menu-box");if (menuElements.length > 0) {var menuElement = menuElements[0];menuElement.style.left = element.offsetLeft + 17 - 127 + "px";menuElement.className = menuElement.className.replace('hidesortmenu','');}}};}();

Display template configuration

To use the display template, you need to add a content search web part to a page in SharePoint and configure it correctly.

As we discussed earlier, you can change the information displayed in the document preview by adding properties like in the screenshot.

The properties under HeaderTitles will change the name of the columns of the search results. If it is left empty, the managed property names will be used as column names. We added this functionality because Managed properties don’t always have a logical name.

The PreviewDialogTitle option is used in order to set the value of a certain managed property of the document as title of the document preview.

The managed properties that are not important, and don’t need their own column can still be visualized on the preview panel.

The final result will look something like this.

Thanks for reading, feel free to comment in the section bellow.

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<KeyValuePair<T, U>>) {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<KeyValuePair<T, U>>, 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<T extends number | string, U extends any>{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<string, Dictionary<string, string>> = null;constructor(name: string) {this.resourceName = name;this.setLanguageDictionary();}protected setLanguageDictionary(): void {throw new Error('setLanguageDictionary not implemented!');};getLanguages(): Dictionary<string, Dictionary<string, string>> {const self = this;return self.languageDictionary;}getResourceName(): string {const self = this;return self.resourceName;}getTranslations(language: string): Dictionary<string, string> {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<C.KeyValuePair<string, string>> = [{ key: 'title', value: 'Home Title' },{ key: 'helloWorld', value: 'Hello World!' }];let Translations_nl: Array<C.KeyValuePair<string, string>> = [{ key: 'title', value: 'Home Titel' },{ key: 'helloWorld', value: 'Hallo wereld!' }];self.languageDictionary = new C.Dictionary<string, C.Dictionary<string, string>>([{ 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<ResourceBase>;preferredLanguage: string = 'en';constructor() {this.$resources = [];}addResource(resource: ResourceBase): void {const self = this;self.$resources.push(resource);}getResources(): Array<ResourceBase> {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<string, Dictionary<string, string>> = null;private $dictionary: Dictionary<string, string> = null;constructor() {this.$resourceDictionary = new Dictionary<string, Dictionary<string, string>>();}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<string, string> = null;if (self.$resourceDictionary.containsKey(k)) {tmpDictionary = self.$resourceDictionary.getValue(k);}else {tmpDictionary = new Dictionary<string, string>();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:

<div class="panel panel-default"><div class="panel-heading"><span>{{vm.resourceSvc.getLocalResource('Home.title')}}</span></div><div class="panel-body"><div class="row"><div class="col-lg-12"><h1>{{vm.resourceSvc.getLocalResource('Home.helloWorld')}}</h1></div></div></div></div>

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!

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: '<h1>Hello World!</h1>',});}, 4000, true);}

• View (html)

  <div class="panel panel-default"><div class="panel-heading"><span>Home Title</span></div><div class="panel-body"><div class="row"><div class="col-lg-12"><h1>Hello World!</h1></div></div></div></div>

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: `<h1>${HomeMessages.helloWorld}</h1>`,});}, 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.

<div class="panel panel-default"><div class="panel-heading"><span>{{::vm.homeResources.title}}</span></div><div class="panel-body"><div class="row"><div class="col-lg-12"><h1>{{::vm.homeResources.helloWorld}}</h1></div></div></div></div>

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!