Creating Angular 2 Web Parts for SharePoint

Copyright from: www.cardinalsolutions.com

In this article, we will be discussing how to create and load multiple Angular 2 web parts on a page in SharePoint 2013. We will take the following steps to create our solution:

1. Technologies and Starting Points
2. Goals and Challenges
3. Adding Web Part Code
4. Debugging
5. Enabling Prod Mode
6. Bundling
7. Uploading to SharePoint
8. Conclusion

Technologies and Starting Points

As of the writing of this blog post, Angular 2 is in Release Candidate 4. It is possible (or perhaps even likely) that some of the functionality and steps detailed in this article will change. We will assume knowledge of SharePoint 2013 development tasks including how to update master pages and add web parts. Knowledge of Angular 2, TypeScript and JavaScript in general are highly recommended in order to create useful web parts that are more complex than the simple example demonstrated in this article. Knowledge of SystemJS and SystemJS builder will be required to properly bundle and load code for the browser, however, this article will cover some of the more challenging portions of this task.

One of the most difficult questions when starting a project is what template or starter solution to begin with. In this article, I started with a combination of the Angular 2 Quickstart and Dan Wahlin’s Angular2-JumpStart. The Angular 2 Quickstart gives the extreme basics needed to start an Angular 2 applications and doesn’t include much of the unnecessary functionality for web parts such as routing. Dan’s Angular2-JumpStart gives us a good beginning on the necessary functionality for bundling.

For our file structure, we will create the following basic folders and files (the link to the final source code can be found at the bottom of this article):

We have our typical files necessary for an Angular 2 application including package.json, tsconfig.json, typings.json, and the node_modules folder. We keep our primary source code within the src folder with all Angular 2/TypeScript code in the app subfolder.

Notice that in our completed file structure, we have systemjs.config.js and index.html files in both the root folder and the src folder. The files in the src folder are used for debugging and bundling the code.  The files in the root folder can be used to test our bundled files that will be created in the dist folder.

Goals and Challenges

Before we go too deep into our solution, we need to review the goals for our solution and the challenges that we must overcome. Our goals:

• Create web parts for Angular 2 to be hosted in SharePoint 2013
• One or more web parts may be on a page within SharePoint
• Angular 2 code should be bundled so that only the necessary code should be loaded on a page (i.e. we don’t want the code for web parts that aren’t on our page to load)

Based on these goals, we run into several challenges. Most Angular 2 examples are created as single page applications. Because an Angular 2 application is bootstrapped to one HTML tag (such as within the Angular 2 Quickstart), we can’t create a single application that encompasses all web parts, but instead we must create multiple applications. We will create an Angular application for each web part.

Bundling will be a challenge as well. We will have to only load the code for the web parts that are used on the page. We may only bootstrap components that are present on the current page. We will bundle the code for each web part separately so that we can load JavaScript files based on which web parts are included on the page.  We will discuss bundling in more detail later in this article.

Adding Web Part Code

If you have any code or subfolders in the src/app folder (such as those you might create via the Angular 2 Quickstart tutorial), remove them.

We need a location to store our web part code, so we will create a folder under src/app titled wp1. Create a file in the wp1 folder named wp1.component.ts. This file will contain the code for our web part. The contents of this file should be as follows:

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

@Component({
    selector: 'web-part-1',
    template: '

{{text}}
'
})
export class WebPart1Component {
    text: string = 'Web Part 1 Loaded';
}

This simplistic code will create an h1 heading and will display “Web Part 1 Loaded” in the heading once Angular has loaded and processed the code.

Next we create a main.ts file under the wp1 folder. This will be the entry point for the Angular application within our web part. The contents of this file should be as follows:

import {bootstrap} from '@angular/platform-browser-dynamic';

import {WebPart1Component} from './wp1.component';

bootstrap(WebPart1Component);

Here we are importing our component file created before, then bootstrapping the application with this component.

Next we will update our systemjs.config.js file within our src folder. We use the file created within the Angular 2 Quickstart as a starting point. We need to update the map and packages section to include the new wp1 code (and remove the app sections as we removed the app code before). Our systemjs.config.js file should now look like the following:

(function(global) {
  // map tells the System loader where to look for things
  var map = {
    'wp1':                        'src/app/wp1',
    '@angular':                   'node_modules/@angular',
    'rxjs':                       'node_modules/rxjs'
  };
  // packages tells the System loader how to load when no filename and/or no extension
  var packages = {
    'wp1':                        { main: 'main.js',  defaultExtension: 'js' },
    'rxjs':                       { defaultExtension: 'js' }
  };

    var ngPackageNames = [
    'common',
    'compiler',
    'core',
    'http',
    'platform-browser',
    'platform-browser-dynamic',
    'router',
    'router-deprecated',
    'upgrade',
  ];
  // Add package entries for angular packages
  ngPackageNames.forEach(function(pkgName) {
    packages['@angular/'+pkgName] = { main: 'bundles/' + pkgName + '.umd.js', defaultExtension: 'js' };
  });
  var config = {
    map: map,
    packages: packages
  }
  System.config(config);
})(this);

Next, we need to update the index.html file from the Angular 2 Quickstart within the src folder to include our wp1 files and the selector tag for the web part (and again remove any references to app from the Quickstart code). When completed, the index.html file will contain the following: