Using TypeScript in a SharePoint 2013 App

Scot Hillier

by Scot Hillier on 4/8/2015

Share this:
Print

Article Details

Date Revised:
4/8/2015

Applies to:
Angular, javascript, jQuery, SharePoint-hosted app, TypeScript


TypeScript has been around for several years now trying to gain traction in the web development community. For those who are unfamiliar with TypeScript, it is a typed superset of JavaScript that compiles to pure JavaScript. TypeScript allows enterprise developers to create better JavaScript-intensive applications by introducing variable typing, classes and modules. Personally, I have been lukewarm on TypeScript in the past. While I understand the value it brings, the teams I work with typically are not ready to use it for application development. Therefore, they quickly dismiss the idea. For me that all changed when the Angular team announced that the 2.0 version would be built on TypeScript. This union means that TypeScript has arrived, and you should learn to use it. In this article, I’ll show you how to implement TypeScript in your SharePoint apps and introduce you to some of the basics. You can find the complete sample app for this article in the IT Unity repository.

TypeScript is evolving quickly, so you should make sure that you have the latest engine update before using it for development. This article uses TypeScript 1.4 for Visual Studio 2013. As TypeScript has grown, the Visual Studio team has done a great job implementing associated tools to support developers. Unfortunately, some of this tooling does not “light up” in the current SharePoint app project template, so we’ll have to take some extra steps. Nonetheless, support for SharePoint developers using TypeScript is much better than a year ago when I had to edit the Visual Studio project files by hand to include support.

For this article, I’m going to create a SharePoint-hosted app that uses TypeScript to make a REST call into the User Profile Service. That call will retrieve the current user’s display name and photo, which will be used to welcome them on the app home page. The data will be bound to the home page using knockout.

Adding TypeScript support to the SharePoint app

In order to get started with TypeScript, simply create a new SharePoint-hosted app in Visual Studio 2013. After the project is created, delete the default app.js file. Now, right-click the scripts folder and select Add New Item from the context menu. In the Add New Item dialog, type typescript in the search box. Then add a new TypeScript file named app.ts. In a standard Visual Studio web project, you can simply rename a JS file with a TS extension to create a TypeScript file, but that does not currently work in the SharePoint app project template.

Add a TypeScript file called app.ts to a new SharePoint-hosted app created in Visual Studio 2013

Figure 1, Adding a TypeScript file

After you’ve added the new TypeScript file, you’ll see it open in a split screen. The left-hand side of the screen shows the TypeScript view. The right-hand side of the screen shows the compiled JavaScript view. At this point, you won’t see code in the TypeScript side, and thus no associated compiled JavaScript. Before you can write that code, the app will need references to support jQuery, knockout and SharePoint libraries.

The SharePoint-hosted app project template already contains a jQuery reference and some SharePoint references. The knockout library is missing, however. In the Solution Explorer, right-click the project and select Manage NuGet Packages from the context menu. Search for knockoutjs and add the library to the project.

Use the NuGet Package Manager to add the knockoutjs library to the project

Figure 2, Adding knockout support

In order to use third-party libraries like knockout with TypeScript, you must add special “typings” definitions to the project. In standard Visual Studio web projects, you can simply right-click the third-party library and search for associated typings, but that tooling does not “light up” in SharePoint app projects. Therefore, you have to search for typings definitions in the NuGet Package Manager. With the window still open, search for jquery.typescript.definitelytyped and add the definition. Repeat the process for knockout.typescript.definitelytyped and sharepoint.typescript.definitelytyped.

Add the typings definitions for jquery.typescript.definitelytyped, knockout.typescript.definitelytyped and sharepoint.typescript.definitelytyped

Figure 3, Adding typings definitions

In standard Visual Studio web projects, typings are automatically referenced. In a SharePoint project, however, you must add the references directly to the TS file using the “triple whack” syntax at the top of the app.ts file.

/// <reference path="typings/SharePoint/SharePoint.d.ts"/>

/// <reference path="typings/jQuery/jquery.d.ts"/>

/// <reference path="typings/knockout/knockout.d.ts"/>

At this point, you can build the project, which will create an associated app.js file in the project. However, you will not see the file in the Solution Explorer until you add it manually. In the Solution Explorer, click Show All Files. Locate the hidden app.js file, right-click it and select Include in Project. Click Show All Files again to switch back to the normal file view and the app.js file should still be visible. In standard Visual Studio web projects you would not have to go through this process. The compiled JS file always appears underneath the associated TS file in the Solution Explorer. In the SharePoint app project, it’s a bit messier, but it works.

Compiling the app.js file

Figure 4, Compiling the app.js file

Coding the SharePoint app

Now that the TypeScript support is all in place, you can begin coding the functionality. This example will make use of types, module, interface, and class to create the required functionality. A TypeScript module is a container for organizing code and is closely related to the JavaScript concept of a module or a namespace. In TypeScript, you can use the module keyword to define a module. In the sample, a module named Wingtip is defined.

module Wingtip { }

Types and interfaces in TypeScript allow you to define the contract for a function. In this example, the display name and photo link are returned from the User Profile Service for the current user. So, the interface keyword is used to define an interface named WelcomeData along with types to reflect the contract.

module Wingtip {
    interface WelcomeData {
        pictureUrl: string;
        displayName: string;
    }
}

Classes are defined in TypeScript using the class keyword. Classes can contain public and private members. In the example, a class named Welcome is defined to contain the functionality that calls to the User Profile Service. Listing 1 shows the complete code for the sample.

Listing 1, Using TypeScript in a SharePoint app

/// <reference path="typings/SharePoint/SharePoint.d.ts"/>
/// <reference path="typings/jQuery/jquery.d.ts"/>
/// <reference path="typings/knockout/knockout.d.ts"/>
 
module Wingtip {
 
    interface WelcomeData {
        pictureUrl: string;
        displayName: string;
    }
 
    export class Welcome {
 
        //Private members
        private static displayName: string = "";
        private static pictureUrl: string = "";
 
        //Public methods
        public static get_viewModel(): WelcomeData {
            return {
                "pictureUrl": Welcome.pictureUrl,
                "displayName": Welcome.displayName
            };
        }
 
        public static init(): JQueryXHR {
 
            return jQuery.ajax(
                {
                    url: "../_api/SP.UserProfiles.PeopleManager/GetMyProperties",
                    method: "GET",
                    headers: {
                        "accept": "application/json",
                    },
                    success: (data: any, status: string, jqXHR: JQueryXHR) => {
                        Welcome.displayName = data.d.DisplayName;
                        Welcome.pictureUrl = data.d.PictureUrl;
                    }
                }
            );
        }
    }
}

After completing the core coding, you must add additional code for implementing the knockout bindings. You must also set appropriate app permission requests in the app manifest. I won’t cover these activities in this article, because you can easily look over the complete sample in the IT Unity repository. When completed, however, you should be able to run the app and be welcomed with text and your portrait.

The completed SharePoint-hosted app using TypeScript

Figure 5, The completed app

Conclusions

With the recently announced union between Angular and TypeScript, it’s time for SharePoint developers to take another look. While support for TypeScript in Visual Studio is excellent for standard web projects, life is a little more difficult in SharePoint app projects. With this article as guidance, however, you’ll be able to integrate TypeScript into your SharePoint apps and take advantage of strong typing, modules, classes and interfaces.


Topic: JavaScript and jQuery

Sign in with

Or register

  • To follow along with this tutorial I am using Visual Studio 2013 and SharePoint online. If you log in as "Admin" to Visual Studio 2013 you will not get an "app.js" file. For some reason when you log in as admin .ts files will not compile to .js files.
  • For automatic referencing of typings or other typescript files, the solution project files can be edited and a "property group" added for a better experience.
    Reference from: http://typescript.codeplex.com/wikipage?title=Compile-on-Save
  • Had to go the "edit the Visual Studio project files" route with VS2015 RC