December 2, 2017

1580 words 8 mins read

SharePoint Framework & Angular Elements : Building your first Web Part

SharePoint Framework & Angular Elements : Building your first Web Part

Now that you are excited by the introduction of Angular Elements, a Google technology that enables us, Enterprise Developers, to use Angular as a Development tool rather than a full blown framework, how cool would it be to start using it TODAY, using its current alpha/beta release? Well, you’re at the right place!

Angular Elements and SharePoint Framework are still in their developments. This codes is based on pre-release of Angular Elements and a very “rough” integration with the SharePoint Framework. I am still pushing those samples so you can start playing with the technology. Please don’t use any of this in production as of today. I will update the posts and code when better support will be offered by both Angular and SharePoint Framework.

This post is part of a series of post on integrating the SharePoint Framework with Angular Elements

Getting started

The first step for getting started is to create your SharePoint Framework project and select the “No Framework” option. That will let us import our favorite framework (Angular Elements!) at a later time. To speed up the initialization of the project, use the --skip-install option to only deploy the necessary files. We’ll run the npm install later when everything will be ready!

Adding Angular Elements

Your project is now ready for Angular! How do we add Angular and Angular Elements to the mix? Well, it’s pretty simple, thanks to their npm packages! Use the following package.json to make sure you get the proper dependencies and references in your project.

{
  "name": "spfx-ng-webparts",
  "version": "0.0.1",
  "private": true,
  "engines": {
    "node": ">=0.10.0"
  },
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  },
  "dependencies": {
    "@angular/animations": "angular/animations-builds",
    "@angular/common": "angular/common-builds",
    "@angular/compiler": "angular/compiler-builds",
    "@angular/compiler-cli": "angular/compiler-cli-builds",
    "@angular/core": "angular/core-builds",
    "@angular/elements": "angular/elements-builds#labs/elements",
    "@angular/platform-browser": "angular/platform-browser-builds",
    "@angular/platform-browser-dynamic": "angular/platform-browser-dynamic-builds",
    "@angular/platform-server": "angular/platform-server-builds",
    "@microsoft/sp-core-library": "~1.3.4",
    "@microsoft/sp-lodash-subset": "~1.3.4",
    "@microsoft/sp-office-ui-fabric-core": "~1.3.4",
    "@microsoft/sp-webpart-base": "~1.3.4",
    "@ngtools/webpack": "^1.8.0",
    "@types/webpack-env": ">=1.12.1 <1.14.0",
    "rxjs": "^5.5.2"
  },
  "devDependencies": {
    "@microsoft/sp-build-web": "~1.3.4",
    "@microsoft/sp-module-interfaces": "~1.3.4",
    "@microsoft/sp-webpart-workbench": "~1.3.4",
    "@types/chai": ">=3.4.34 <3.6.0",
    "@types/mocha": ">=2.2.33 <2.6.0",
    "ajv": "~5.2.2",
    "enhanced-resolve": "3.4.1",
    "exports-loader": "^0.6.4",
    "gulp": "~3.9.1",
    "uglify-es": "^3.2.0",
    "raw-loader": "^0.5.1",
    "sass-loader": "^6.0.6",
    "style-loader": "^0.19.0",
    "uglifyjs-webpack-plugin": "^1.1.1",
    "webpack-bundle-analyzer": "^2.9.1",
    "webpack-merge": "^4.1.1"
  }
}

##Modifying your build process To enable Angular Elements (and AOT compilation) in your project, you have to make some changes to your TypeScript and your build configurations. The following files should replace your tsconfig.json and gulpfile.js files! This will enable your solution to transpile your TypeScript to ES2015 and will ask Angular to take care of the JS/TS packaging.

{
  "compilerOptions": {
    "target": "es2015",
    "forceConsistentCasingInFileNames": true,
    "module": "commonjs",
    "jsx": "react",
    "declaration": true,
    "sourceMap": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "types": ["webpack-env"],
    "lib": ["dom", "es2015"]
  }
}

'use strict';

const gulp = require('gulp');
const path = require('path');
const build = require('@microsoft/sp-build-web');
const merge = require('webpack-merge');
const { AngularCompilerPlugin } = require('@ngtools/webpack');
const webpack = require('webpack');
const UglifyJSPlugin = require('uglifyjs-webpack-plugin');

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    if (build.configureWebpack.buildConfig.production) {
      generatedConfiguration.plugins.forEach((plugin) => {
        if (plugin instanceof webpack.optimize.UglifyJsPlugin) {
          var index = generatedConfiguration.plugins.indexOf(plugin);
          generatedConfiguration.plugins.splice(index, 1);
        }
      });

      generatedConfiguration.plugins.push(new UglifyJSPlugin());
    }

    Object.assign(generatedConfiguration.resolve, { extensions: ['.ts', '.js'] });
    generatedConfiguration.module.rules = [
      { test: /\.ts$/, loader: '@ngtools/webpack' },
      {
        test: /\.scss$/,
        use: ['raw-loader', 'sass-loader'],
      },
      {
        test: /\.css$/,
        loader: ['raw-loader', 'css-loader'],
      },
      { test: /\.html$/, loader: 'raw-loader' },
    ];

    generatedConfiguration.plugins.push(
      new AngularCompilerPlugin({
        tsConfigPath: path.resolve('./tsconfig.json'),
        entryModule: path.resolve('src/elements/elements') + '#NgElementDemos',
      })
    );

    return generatedConfiguration;
  },
});

build.typescript.enabled = false;
build.tslint.enabled = false;

build.initialize(gulp);

Add the Angular Elements plumbing

To use the magic provided by Angular Elements, it’s important to lay out some foudations for any of your Web Parts that live in that solution. Because Angular Elements leverages the Web Components proposed standard, it’s important to “shim” it in case the browser used does not work already with Web Components (I’m looking at you, Edge…) and also to build the basic Module that will take care of embedding you Angular components within that Web Component.

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

@NgModule({})
export class ElementsModule {}

import 'zone.js';

(function () {
  'use strict';

  if (window['WC_SHIMMED']) return;

  (() => {
    'use strict';
    if (!window.customElements) return;
    const a = window.HTMLElement,
      b = window.customElements.define,
      c = window.customElements.get,
      d = new Map(),
      e = new Map();
    let f = !1,
      g = !1;
    (window.HTMLElement = function () {
      if (!f) {
        const a = d.get(this.constructor),
          b = c.call(window.customElements, a);
        g = !0;
        const e = new b();
        return e;
      }
      f = !1;
    }),
      (window.HTMLElement.prototype = a.prototype);
    Object.defineProperty(window, 'customElements', { value: window.customElements, configurable: !0, writable: !0 }),
      Object.defineProperty(window.customElements, 'define', {
        value: (c, h) => {
          const i = h.prototype,
            j = class extends a {
              constructor() {
                super(), Object.setPrototypeOf(this, i), g || ((f = !0), h.call(this)), (g = !1);
              }
            },
            k = j.prototype;
          (j.observedAttributes = h.observedAttributes),
            (k.connectedCallback = i.connectedCallback),
            (k.disconnectedCallback = i.disconnectedCallback),
            (k.attributeChangedCallback = i.attributeChangedCallback),
            (k.adoptedCallback = i.adoptedCallback),
            d.set(h, c),
            e.set(c, h),
            b.call(window.customElements, c, j);
        },
        configurable: !0,
        writable: !0,
      }),
      Object.defineProperty(window.customElements, 'get', { value: (a) => e.get(a), configurable: !0, writable: !0 });
  })();

  /**
  @license
  Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
  This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
  The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
  The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
  Code distributed by Google as part of the polymer project is also
  subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
  */
  window['WC_SHIMMED'] = true;
})();

Building your Angular Component

Then, it’s time for the actual work to happen. You need to create your Angular component using regular Angular code and you will want to tie it to you SharePoint Framework Web Part.

The necessary files for the component to work are its logic, its template and its styles files. Then, those files will be all mixed together and exported as a self-bootstrapped Web Component.

hello-world.ts

import { Component, NgModule, Input, ViewEncapsulation } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'hello-world',
  templateUrl: `./hello-world.html`,
  styleUrls: ['hello-world.scss'],
  encapsulation: ViewEncapsulation.None,
})
export class HelloWorld {
  @Input() description: string;
}

@NgModule({
  imports: [BrowserModule],
  declarations: [HelloWorld],
  entryComponents: [HelloWorld],
})
export class HelloWorldModule {
  ngDoBootstrap() {}
}

hello-world.html

<div class="helloWorld">
  <div class="container">
    <div class="row">
      <div class="column">
        <span class="title">Welcome to SharePoint!</span>
        <p class="subTitle">Customize SharePoint experiences using Web Parts.</p>
        <p class="description">{{ description }}</p>
        <a href="https://aka.ms/spfx" class="button">
          <span class="label">Learn more</span>
        </a>
      </div>
    </div>
  </div>
</div>

styles.scss

@import 'node_modules/@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

.helloWorld {
  .container {
    max-width: 700px;
    margin: 0px auto;
    box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.2), 0 25px 50px 0 rgba(0, 0, 0, 0.1);
  }

  .row {
    @include ms-Grid-row;
    @include ms-fontColor-white;
    background-color: $ms-color-themeDark;
    padding: 20px;
  }

  .column {
    @include ms-Grid-col;
    @include ms-lg10;
    @include ms-xl8;
    @include ms-xlPush2;
    @include ms-lgPush1;
  }

  .title {
    @include ms-font-xl;
    @include ms-fontColor-white;
  }

  .subTitle {
    @include ms-font-l;
    @include ms-fontColor-white;
  }

  .description {
    @include ms-font-l;
    @include ms-fontColor-white;
  }

  .button {
    // Our button
    text-decoration: none;
    height: 32px;

    // Primary Button
    min-width: 80px;
    background-color: $ms-color-themePrimary;
    border-color: $ms-color-themePrimary;
    color: $ms-color-white;

    // Basic Button
    outline: transparent;
    position: relative;
    font-family: 'Segoe UI WestEuropean', 'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', sans-serif;
    -webkit-font-smoothing: antialiased;
    font-size: $ms-font-size-m;
    font-weight: $ms-font-weight-regular;
    border-width: 0;
    text-align: center;
    cursor: pointer;
    display: inline-block;
    padding: 0 16px;

    .label {
      font-weight: $ms-font-weight-semibold;
      font-size: $ms-font-size-m;
      height: 32px;
      line-height: 32px;
      margin: 0 4px;
      vertical-align: top;
      display: inline-block;
    }
  }
}

index.ts

//web components ES5 shim
import '../../../elements/wc-shim';
import { registerAsCustomElements } from '@angular/elements';
import { platformBrowser } from '@angular/platform-browser';

import { HelloWorld, HelloWorldModule } from './hello-world';
import { HelloWorldModuleNgFactory } from './hello-world.ngfactory';

registerAsCustomElements([HelloWorld], () =>
  platformBrowser().bootstrapModuleFactory(HelloWorldModuleNgFactory)
).catch((err) => console.log(err));

Configuring your WebPart

It’s now the time inject that component in your SharePoint Framework Web Part. Using the HelloWorld class will make it available and will also act as your this.properties bag. Very clever and simple to use. You have to note 2 things. The usage of HelloWorld as the Properties type passed in the class declaration and the render method that simply embeds the custom element and passes in the name properties!

HelloWorldWebPart.ts

import './elements';
import { HelloWorld } from './elements/hello-world';
import { NgElement } from '@angular/elements';

import { Version } from '@microsoft/sp-core-library';
import { BaseClientSideWebPart, IPropertyPaneConfiguration, PropertyPaneTextField } from '@microsoft/sp-webpart-base';

export default class HelloWorldWebPartWebPart extends BaseClientSideWebPart<HelloWorld> {
  constructor() {
    super();
  }

  public render(): void {
    this.domElement.innerHTML = `
      <hello-world
        name="${this.properties.name}">
      </hello-world>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: 'Hello World Configuration',
          },
          groups: [
            {
              groupName: 'Options',
              groupFields: [
                PropertyPaneTextField('name', {
                  label: 'Name',
                }),
              ],
            },
          ],
        },
      ],
    };
  }
}

You will also have to make some light changes to your config.json file to indicate to Angular your new entry points and to specify your Module.

config.json

{
  "$schema": "https://dev.office.com/json-schemas/spfx-build/config.2.0.schema.json",
  "version": "2.0",
  "bundles": {
    "hello-world-web-part": {
      "components": [
        {
          "entrypoint": "./src/webparts/helloWorld/HelloWorldWebPart.ts",
          "manifest": "./src/webparts/helloWorld/HelloWorldWebPart.manifest.json",
          "entryModule": "./src/webparts/helloWorld/elements/hello-world",
          "entryModuleName": "HelloWorldModule"
        }
      ]
    }
  },
  "externals": {},
  "localizedResources": {}
}

Run your webpart

Once your Web Part is ready, you can finally run it using gulp serve and see the result directly in your SharePoint Workbench!

Enjoy!

Now that your webpart works, I’ll let you play around and explore the joys of the SharePoint Framework with Angular Elements!

Resources

Angular Angular Elements SharePoint Framework
comments powered by Disqus
I'm killing the SPFx Angular Boilerplate... And it's a good thing!

I'm killing the SPFx Angular Boilerplate... And it's a good thing!

December 1, 2017

A bit of background

I’ve been working in the last few months to understand better the integration possibilities between Angular and the famous SharePoint Framework and I had a lot of fun discovering this landscape! I’ve been building some kind of a workaround with the help of some resources being made available by Microsoft a couple of months ago (funny story, I’m writing this blog post at the exact same coffee shop in a suburb of Montreal where that journey started 10 months ago) and I’ve been touring with a session to show that it was indeed possible to play with Angular and SharePoint, even though I was not recommending it for anyone who wanted to push that code to production. It was more a proof of concept than a future-proof approach. We had great conversations with Andrew Connell, Waldek Mastykarz, Marc D. Anderson and even a couple of debates with Sahil Malik. Even though it was a great learning resource (especially for anyone wanting to try out Angular in a SharePoint context), this solution had to die, some day…

SharePoint Framework and Angular - Walkthrough of the SPFx Angular Boilerplate

SharePoint Framework and Angular - Walkthrough of the SPFx Angular Boilerplate

August 1, 2017

In this post, we will cover the general concepts used to make the SharePoint Framework Angular Boilerplate work and how it solves the challenges that were preventing the production use of both technologies together.

SharePoint Framework and Angular - Introducing the SPFx Angular Boilerplate

SharePoint Framework and Angular - Introducing the SPFx Angular Boilerplate

July 31, 2017

So… This had to happen. Being an Office Developer and using Angular as my main UI framework, I really wanted to find a solution for supporting Angular in the modern SharePoint development toolchain, the SharePoint Framework. I’ve been starting my journey where Microsoft left (the angular2-prototype proof-of-concept that was created by some of the Microsoft folks) and made sure we can improve it to make it usable and supportable in the long run.