Getting started with new SharePoint Framework (SPFx)

On May the 4th Microsoft announced a new development framework for SharePoint, based on pure client side technologies. This framework would be utilising a combination of Node.js, Gulp, TypeScript, React and Knockout. It marked a radical change to the way we develop  apps using established open source frameworks for pure client side with SharePoint office 365 and eventually SharePoint 2016.

Yesterday (18th August) Microsoft announced the release of SharePoint framework in Preview: See announcement: SharePoint Framework Developer Preview Release.  So we are going to create a new app with this framework.

Creating a Hello World app

Microsoft have provided a supporting GitHub project containing the docs behind this framework. From this, I had an opportunity to play with this framework to see how easy it was to get it up and running… and it was surprisingly painless!

In fairness, I have been using a similar technique to develop SharePoint UX/UI and therefore have many of the tools already installed and working. The instructions on GitHub were bang on the money – straight forward and clear. However, I am avid Windows user and have heard there are issues in GitHub that suggest that the MAC and Linux instructions may not be fully working yet.

Before starting this, ensure that you follow the ‘getting started’ section on GitHub:

In addition, have a editor installed for this demo. I have a preference for Visual Studio Code and this is a great lightweight code editor, open-sourced and free. It offers great additional performance, has many extensions, and finally has a great range of language support including the new technologies and languages used in the SharePoint Framework. Go to code.visualstudio.com for more details.

Once you have everything setup, you are ready to build your first app.

Creating a Hello world app with knockout

Create a new folder for your app. In my experience keep the path short, node_modules contain long dependency chains that make the path very long sometimes beyond the 256 character path limit. e.g.  Run “md spfx-hw”.

spfx-hw-create-folder

Run “yo @microsoft/sharepoint” (note: this is case sensitive).

spfx-hw-solution-name

You will be presented with the following questions:

  • “What is your solution name?” – Enter “HelloWorld”
  • “Where do you want to place the files?” – Using the arrow keys, choose “Use Current Folder”
  • “What is your webpart name?” – You can keep the default: HelloWorld
  • “What is your webpart description?” – You can enter anything for this, such as “Example Hello World SPFx Application”
  • “What Framework would you like to use?”
    • The options are for the moment are:
      • No JavaScript Framework
      • React
      • Knockout
    • Use the arrow keys and select Knockout.

spfx-hw-yo-full-options

This will now run through and download the dependant node_modules, this process can take a while.

spfx-hw-yo-finished

Once this has finished, give it a go, run “gulp serve”. This will build and then open a browser window to the local version of the workbench on your machine, initially the workbench will be empty.

spfx-hw-empty-workbench

Click on the plus icon and you should see your new web part.

spfx-hw-workbench-add-webpart

Now you have your own SharePoint client web part.

spfx-hw-workbench-with-hello-world

If you are unfamiliar with the advantages of working this way, you can start to edit the files and check the results in the browser in real-time. The gulp watch module will re-compile any asset into your app and refresh the browser automatically to show you the result.

Note, this app was created by using a preview framework, it’s dependencies may break at any time during the preview phase.

Example Hello World app

HelloWorldSPFXExample

For the hello world app as generated above, I started to customise the web part properties as I was eager to play with knockout to see the binding and real-time updates in action.

I added a some new web part properties to demo the working examples and sample control types that are not working i.e. not bound to properties in the HTML template. These web part properties also contains direct links to their relevant APIs so you can see their full definition.

So to get started, open the app in Visual Studio Code by running “code .”.

vs-code-first-open

Breaking down the Yeoman generated files

When the Yeoman generate configures the app, it will generate the following folders and files:

/.vscode – This folder contains configuration for Visual Studio Code for customisations of the editor and task runner to utilise Gulp.
/config – This contains configuration for Typescript Definitions, Azure Deployment, Azure CDN, deployment, and gulp task configurations.
/dist – bundled distributed output files.
/lib – compiled files from Typescript to JavaScript, SASS to CSS, Typescript definitions for your web part code.
/node_modules – this contains all of the NPM dependencies, around 814 node modules.
/src – This is the source code for your web part, and the main location for writing the code that your web part uses.
/temp – contains the workbench itself, HTML and JavaScript.
/typings – The Typescript definition files.

.editorconfig – editor configuration file for other editors such as WebStorm, Brackets, Eclipse
.gitattributes – used to configure Git attributes, in this case normalisation of end of lines for different platforms.
.gitignore – folders and files that are ignored, typically node_modules, dist, temp, items that are built and don’t represent the source code. These files and folders will not be stored in a Git Repository.
.npmignore
– files and folders to exclude from NPM packages.
.yo-rc.json – Yeoman configuration file.
gulpfile.js
– This is the gulp task settings and configuration, this file contains all the commands that you run to develop, build, serve and test the application.
hello-world.njsproj – support for Visual Studio with Node.js tools installed.
package.json – contains a definition for NPM, such as dependencies, tasks, tests to run.
README.md – a readme file, this is a markdown file for GitHub, this is a template, in anticipation of publishing to a repository such as GitHub or Visual Studio Online, as an entry point into documentation of your project.
tsconfig.jsonconfiguration for Typescript.

Web Part specific files

In the “/src/webparts/helloWorld” folder, you will see that Yeoman has created the following files:

HelloWorld.module.scssSASS file for generating CSS for the web part.
HelloWorld.module.scss.ts – Typescript file defining class names for the SASS classes to bind with Knockout.
HelloWorld.template.html – The partial template HTML file for the web part, many of the classes and HTML are based on the Office UI Fabric.
HelloWorld.ViewModel.ts – Typescript files for the Knockout View Model and bindings.
HelloWorldWebPart.ts – Typescript file for the web part class containing the bindings to the HTML template, property pane settings and web part functionality.
HelloWorldWebPart.minifest.json – JSON file containing the version, title of the app, default properties (for the property pane), group and description.
IHelloWorldWebPartProps.ts – Typescript file defining an interface for the properties for the property pane.

Web Part specific folders

/loc/ – folder containing strings to internationalise you web part from the start, here application strings are defined.

  • /loc/en-us.js – a JSON object that defines the objects to a string.
  • /loc/mystrings.d.ts – Typescript file defining the names of properties to use for the strings, in a interface.

/tests/ – this contains your tests, using the Karma Test Environment with the Mocha test framework and sinon-chai extension to Chai in a PhantomJs browser.

  • /tests/HelloWorld.test.ts – your web part tests.

Adding Properties to the Properties Pane

In the HelloWorldWebPart.ts declaration, import the following from ‘@Microsoft/sp-client-preview’, this will allow you access objects used in the Property Pane Settings class. I have added more than I need here, this is because I have added extra examples on the repo for this on GitHub.

// import extra field types into the pane
PropertyPaneHorizontalRule,
PropertyPaneButton,
PropertyPaneCheckbox,
PropertyPaneDropdown,
PropertyPaneLabel,
PropertyPaneLink,
PropertyPaneSlider,
PropertyPaneToggle,
PropertyPaneChoiceGroup

 

In the HelloWorldWebPart.ts class, we need to define some private variables.

// add new properties
private _meaningfulMessage: KnockoutObservable<string> = ko.observable('');
private _welcomeUser: KnockoutObservable<string> = ko.observable('')

In the HelloWorldWebPart.ts constructor, at the bottom of the constructor.

// add notification
this._welcomeUser.subscribe((newValue: string) => {
  this._shouter.notifySubscribers(newValue, 'welcomeUser');
});
this._meaningfulMessage.subscribe((newValue: string) => {
  this._shouter.notifySubscribers(newValue, 'meaningfulMessage');
});

In the HelloWorldWebPart.ts constructor bindings method, this ensures that when the Property pane is updated the page variables are up dates automatically thus updating the user interface.


// added new properties to the context
welcomeUser: this.properties.welcomeUser,
meaningfulMessage: this.properties.meaningfulMessage

In the HelloWorldWebPart.ts, alter render() method:


//add new fields to render method
this._meaningfulMessage(this.properties.meaningfulMessage);
this._welcomeUser(this.properties.welcomeUser);

In the HelloWorldWebPart.ts, alter the propertyPaneSettings() method, this method defines the properties and their controls. Microsoft have provided a collection of classes (as shown in the import earlier). These define which HTML elements are used to set the properties, for example below PropertyPaneTextField renders a text field.

{
   header: {
     description: strings.PropertyPaneDescription
   },
   groups: [
    {
      groupName: strings.BasicGroupName,
      groupFields: [
        PropertyPaneTextField('description', {
          label: strings.DescriptionFieldLabel
        })
      ]
    },

    // extra parameter within the same property pane
    {
       groupName: strings.WelcomeUserGroupName,
       groupFields: [
         PropertyPaneTextField('welcomeUser', {
           label: strings.WelcomeUserFieldLabel
         })
       ]
    },
    {
      groupName: strings.MeaningfulMessageGroupName,
      groupFields: [
        PropertyPaneTextField('meaningfulMessage', {
          label: strings.MeaningfulMessageFieldLabel
        })
      ]
    }
  ]
}

 

Add new property pane definitions to the IHelloWorldWebPartProps.ts file:


// add extra properties to the interface
welcomeUser: string;
meaningfulMessage: string;

Set default properties in the HelloWorldWebPart.minifest.json file, when the app loads the properties defined in the property pane are set to these values initially.


"properties": {
   "description": "Hello World Sample Application",
   "meaningfulMessage": "Software is a great combination between artistry and engineering. (Bill Gates)"
}

The final result…

spfx-hw-workbench-with-hello-world-property-pane

I have uploaded the all the code onto GitHub, see my repository on GitHub  to see this example.

This isn’t the most exciting demo but I wanted to get started and expose the UI for configuring the app to allow quick customisation of the properties.

I am pleased that Microsoft has come up with a new way to develop for SharePoint in Office 365. Much of the more traditional techniques are not supported or are being retired, such as the recent support for code based user solutions.

Remember this is preview, this approach is likely to be tweaked based on feedback from the community. If you have any ideas, go to the uservoice site and post them, with enough support they may get implemented.

Further reading

Awesome blog posts and resources on the SharePoint Framework

There are a number of blog posts being written about this framework, Microsoft are also supporting queries about this method of development, these resources can be found on the following sites:

References

Advertisements

One thought on “Getting started with new SharePoint Framework (SPFx)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s