3

SharePoint Framework with Angular 2: Setup

I finally managed to try out the new SharePoint Framework (SPFx), which is a page and part model, built to facilitate the development of client side web parts. I have been developing client-side web parts for some time now, so I have to admit SPFx looks quite promising. The most exciting facts (at least for me) are listed below.

  • We no longer have to endure painful configuration of Content Editor or Script Editor web parts in order to insert client side web parts into the page.
  • We won’t have to configure additional lists to store settings related to our web parts or search other alternatives to achieve this. SPFx introduces the settings property pane which can be easily used for web part customization.
  • And most importantly, encourages the use of client side frameworks that support component based development (frameworks like React, Angular 2, etc.). If you think about the web part simply as a component that is added to a page, the use of such frameworks is well suited indeed.

With that being said, let’s continue to setting up a SPFx project that uses Angular 2. I won’t go into details on how you can install and configure SPFx on your development machine, because that is already explained here. Just make sure you have been through all the steps given in the “SharePoint Framework” section (the accordion on the left) before continuing to read this post.

Start a node.js command prompt and navigate to the place you want to create your project. For example, I am working on “E:\Dev\SP”. Make a new directory here “angular2-app”. Navigate to the newly created directory and initiate the generation of your project structure with Yeoman. Run the following command in cmd:

yo @microsoft/sharepoint

Follow the instructions of the SharePoint Client-side Solution Generator and set the required properties as shown below. As you can see, there is already a possibility of installing a client-side framework out-of-the-box, but since this time we are going with Angular 2, choose here “No javaScript web framework”.

Once the installation and configuration of packages is over, you will get a message that the SPFx solution is successfully created.

In order to start a local web server and try out your web part, run in cmd:

gulp serve

Once in the browser, you can use the plus icons to insert your “HelloWorld” web part anywhere in the page, even multiple times if you need to. You can also configure it by using the settings pane on the right.

Okay, now let’s finally install Angular 2. We will install it with npm package manager. What I usually do is I create a file “package.json” and in it, I add the packages I need. Then, I run npm install and let npm handle everything.

We will do the same, here. Open your SPFx project (you can use any editor you like, I prefer to use Visual Studio Code). Once your project is open, you can see that the file “package.json” is already there and it contains dependencies related to SPFx. You will need to add the dependencies related to Angular 2 and some additional dependencies on which Angular 2 is dependent. So change the dependencies section in your “package.json” as follows.


"dependencies": {
"@angular/common": "^2.0.0-beta.17",
"@angular/compiler": "^2.0.0-beta.17",
"@angular/core": "^2.0.0-beta.17",
"@angular/platform-browser": "^2.0.0-beta.17",
"@angular/platform-browser-dynamic": "^2.0.0-beta.17",
"@microsoft/sp-client-base": "~0.3.0",
"@microsoft/sp-client-preview": "~0.4.0",
"es6-shim": "^0.35.1",
"reflect-metadata": "^0.1.8",
"rxjs": "^5.0.0-rc.1",
"zone.js": "^0.6.26"
}

Once you have everything prepared, you can run npm install in cmd to install all packages.

Once the installation is done, go back in your project and create a folder “app”. Under the newly created folder, create two additional files “app.module.ts” (which will represent the root module of your angular app) and “app.component.ts” (which represents a single component). The structure of your project should look like in the image below.

Open “app.component.ts”. Define your component and specify its selector and template, here. The component I have created is shown below. It basically displays a simple text (description) and inserts an input field.


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

@Component({
  selector: 'app-form',
  template: `
    {{description}}
    <input type="text" />
  `
})

export class AppComponent {
  description: string = "Hello there! Enter your name:"
}

Next, you need to register the component in your “app.module.ts”. You will have to do the same for each additional component you create.


import { NgModule }      from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent }  from './app.component';

@NgModule({
  imports: [BrowserModule],
  declarations: [AppComponent],
  bootstrap: [AppComponent]
})

export class AppModule { }

As you can see in both files “app.component.ts” and “app.module.ts” we have used class decorators, that for now are an experimental feature in TypeScript. If you are getting a warning related to that, make sure you have set “experimentalDecorators” to true in “tsconfig.json”. You can read more on decorators here.

The only thing that you have left now is to bootstrap your root module and launch your angular app. In order to do so, navigate to the file “HelloWorldWebPart.ts” and change the render() function in the following way.


public render(): void {
    this.domElement.innerHTML = ``;

    platformBrowserDynamic().bootstrapModule(AppModule);
  }

Additionally you will have to add imports at the beginning of the file for your app module and for the platform-browser-dynamic package.


import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';

Okay, now save the changes and run gulp serve to launch the app.

When you refresh your web part in the browser, you will probably get an error.

Error: Unable to load web part script resources due to: Error: reflect-metadata shim is required when using class decorators …

This happens due to the fact that you need to import the “reflect-metadata” shim, because you are using class decorators (as mentioned earlier). Additionally, you will have to load the module “zone.js”. Angular uses this library to trigger the change detection engine and to automatically detect that something changed (a DOM event occurred, HTTP request is triggered, a timer is triggered, etc).

Add these two lines at the beginning of “HelloWorldWebPart.ts”.

import 'reflect-metadata';
require('zone.js');

Now, you can finally launch your angular app with no errors and your web part is finally displaying the text and the input field you specified in the template of your component.

The complete code can be found on Github.

Biserka Cvetkovska

3 Comments

  1. Ciao Biserka,
    thanks for your in-depth view on the integration of angular js in the SharePoint Framwork. I will try it with the fabric ui library 😉
    Cheers Hari

  2. Hi Biserka/Hari, did either of you try to use SharePoint Framework +Angular 2 + Office Fabric. Looking at the Fabric docs, it seems only Angular 1.6 is supported but given TypeScript ultimately gets translated into JavaScript , then can we get around the 1.6 restriction.

    • No, I haven’t tried to use Angular 2 + Office UI Fabric. The problem here is that the Angular 1 framework is very different from Angular 2, so I am sure that the current ngOfficeUIFabric components won’t work with Angular 2.

Leave a Reply

Your email address will not be published. Required fields are marked *