Release Notes Drop 6

Wow, it's been a while since we've updated the drop. We've been working a bunch on finalizing our APIs. The biggest news is that 1st release tenants should get to use SPFX, although it's still in preview and not supported for production use. We think about 75% of the farms should be updated by now, with the rest finished in the next day or two.

Getting the new bits

Make sure that your @microsoft/generator-sharepoint npm package is version 0.3.2. To get the latest version, run npm i -g @microsoft/generator-sharepoint@latest

Updating your existing projects

Getting your node modules set up correctly

1 - Open package.json and set the versions of the following packages:

• "@microsoft/sp-client-base": "~0.5.1",

• "@microsoft/sp-build-web": "~0.8.1",

• "@microsoft/sp-client-preview": "~0.7.1"

• "@microsoft/sp-module-interfaces": "~0.5.1",

• "@microsoft/sp-webpart-workbench": "~0.6.1"

if you are referencing sp-webpart-base

• "@microsoft/sp-webpart-base": "~0.2.1"

2 - If you are only using the WebPart components from sp-client-preview, you should remove the reference to it from package.json and config.json. These next steps were copied from the Drop 5 notes.

• i - Add the package via npm i --save @microsoft/sp-webpart-base . This should update the dependencies section of your package.json file to reference "@microsoft/sp-webpart-base":"~0.2.1".

• ii - Update the config.json file in the config folder to add it to the externals section under sp-client-preview "@microsoft/sp-webpart-base": "node_modules/@microsoft/sp-webpart-base/dist/sp-webpart-base.js",

• iii - Update your webpart source code to move the import references from @microsoft/sp-client-preview to @microsoft/sp-webpart-base

2 - delete your NodeModules folder and run npm i
This will update all the packages then optimize the node_modules folder size.

3 - Run gulp nuke to clean up any old build artifacts

4 - run gulp trust-dev-cert to install and trust a developer certificate on your machine (optional, but recommended. You only need to do this once per machine, not once per project)

5 - Edit your config\tslint.json file and remove the last line ("a11y-role": true) and make sure there is no trailing comma left on the line above

6 - Edit your src\webparts\WebPartName.manifest.json file, and add an entry "alias": "WebPartNameGoesHere", before componentType. Clearly, you should replace that with the right alias name. This name is used in things like telemetry and logging.

7 - Run gulp to build your updated project

What changed in this drop?

There are three main things that were tweaked in this drop, mostly around how the property pane is handled

1 - There are specific calls to show the property pane openPropertyPane, and to refresh it refreshPropertyPane. Use these rather than the previous congfigureStart

2 - When creating custom fields in the property pane, you can now pass a context object in. When onDispose and onRender are called, we will pass that context object to you. Should make it easier to create generic field code that can be used on more than one field, rather than having to hard code the field property in the OnRender method itself.

3 - We've also done a bunch of general cleanup in the sp-webpart-base package to the point where it makes sense to make it the new default. We'll remove the previous logic from sp-client-preview in the next drop.

sp-webpart-base

class BaseClientSideWebPart

removed protected configureStart(refreshOnly?: boolean): void;

Added protected onDispose(): void

Modified protected onInit < T >(): Promise<T>' to be 'protected onInit(): Promise<void>

Added protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void

interface IClientSideWebPartStatusRenderer

Modified displayLoadingIndicator(domElement: Element, loadingMessage: string): void to be displayLoadingIndicator(domElement: Element, loadingMessage: string, timeout?: number): void

interface IPropertyPaneCustomFieldProps

Added context?: any

Modified onDispose?: (domElement: HTMLElement, context?: any) => void to be onDispose?: (domElement: HTMLElement, context?: any) => void

Modified onRender: (elem: HTMLElement) => void to be onRender: (domElement: HTMLElement, context?: any) => void

interface IPropertyPaneData

Modified onPropertyChange: (propertyName: string, newValue: any) => void to be onPropertyPaneFieldChanged: (propertyName: string, newValue: any) => void

interface IWebPartContext

Modified environment: Environment to be environment: LegacyEnvironment Added openPropertyPane: () => void

Added refreshPropertyPane: () => void

class LegacyEnvironment

Added the class itself. Note that you shouldn't really use this class. We added it for this drop to support the deprecation of the Environment variable on IWebPartContext. You should instead import{Environment} from '@microsoft/sp-client-base' and then reference Environment.Type

Added public type: EnvironmentType

Here is how the new code looks.

Import Environment and EnvironmentType from sp-client-base:

import {
  Environment,
  EnvironmentType
} from '@microsoft/sp-client-base'

Then in your code, you can use the following to check if local or SharePoint, which is the same as earlier except that it is no longer part of the context:

if(Environment.type == EnvironmentType.Local) {
    alert('local');
} else if(Environment.type == EnvironmentType.SharePoint) {
  alert('SharePoint');
}

Yeoman Generator

Switched to use sp-webpart-base as the main webpart API

Fixed the known Knockout issues

@microsoft/sp-client-base::PageContext replaced with @microsoft/sp-page-context::PageContext @microsoft/sp-client-base ODataTypes replaced with @microsoft/sp-odata-types ODataTypes

What's coming up?

Reworking HttpClient, removing it from sp-client-preview and creating it's own top level package

Removing the SPPageContextInfo window variable and augmenting the PageContext class to contain the same object.

Introducing decorators to make it clear what methods and classes should be virtual and sealed.

We've given a bunch of thought around versioning and serializing and deserializing webpart data. There will be some updated APIs to help with this.

Updating and documenting how to do common build extensibility scenarios (like controlling webpack)