6/09/2017

SharePoint Framework Extensions Developer Preview Is Here!

On 6/6/2017 Microsoft finally announced availability of SharePoint Framework Extensions Developer Preview - a set of allowed customizations to change user experience of sites, lists and document libraries. Drawing a parallel between "classic" SharePoint development and new features - this is a new iteration of JSLink, ScriptLink and custom actions.
Let's review currently available extensions and their usage.
UPDATE: on 8/29/2017 Release Candidate was announced. The post is updated to contain newer version of API.

Getting started with new features

  1. SharePoint Framework Extensions are available for testing through Office 365 Developer Tenants during preview and later across all of the tenants, when they will GA. It means that you need an Office 365 Developer Tenant. Mercifully, you can get free Office 365 Developer Tenant by subscribing to Office 365 Developer Program. Since September the Extensions will be propagated to First Release tenancies.
  2. If you have not yet installed SharePoint Framework, please have a look on the tutorial about SharePoint Framework Development.
  3. If you have already installed previous version of the SPFx then you need to execute the following command to update Yeoman template for SharePoint:
    npm install -g @microsoft/generator-sharepoint
Now you're ready to go.

Application Customizer (ScriptLink)

Application Customizer Extension is a feature that we previously knew as ScriptLink - a customization that is loaded to all the pages.

What can you do with this extension

The most important feature is ability to run custom scripts on a modern page. In the RC you can run your code in onInit method and also subscribe to this.context.application._layoutChangedEvent event.
  1. onInit allows you to run initialization code before the DOM of the page is ready. It also allows to get access to placeholders on the page. This method returns Promise object (similarly to Client Side Web Parts).
  2. this.context.application._layoutChangedEvent is called each time the layout is changing.
Additionally, you can add your markup into a specially provided placeholders in the page's DOM (similar to Placeholders in Master pages and ASP.NET pages).  To add your markup to a placeholder you should write the code similar to:
// receive placeholder
const placeHolder = this.context.placeholderProvider.tryCreateContent(PlaceholderName.Top);
// setting innerHTML of placeholder DOM element
placeHolder.domElement.innerHTML = '<div style="background-color: red;">Attached</div>';

this.context.placeholderProvider is a helper that contains placeholderNames property with the names of all available placeholders, tryCreateContent method to receive a placeholder by name and options and changedEvent to add the handler that will be fired when set of available placeholders for the page was changed.
Some notes:
  1. Only Top, Bottom placeholders are currently available (8/30/2017). Dev team promises to add more.
While configuring Application Customizer in solution package you can provide optional properties. The properties will be available via this.properties property. It can be used, for example, to provide url to some config list.

Field Customizer (Field JSLink)

Field Customizer is a new iteration of Field JSLink. It allows to apply custom rendering to each cell in the field's column.

What can you do with this extension

Customizer allows to insert any HTML into cell's div. There are 3 methods to override: onInit, onRenderCell and onDisposeCell

  1. onInit method allows to run some initialization code and ensure that the execution of this code is finished before rendering.
  2. onRenderCell method is an entry point for actual rendering. You have access to cell's DOM element to render your content. Also, there is a bunch of helpful objects inside this.properties property and event object (such as cell value, field information, List View properties, etc.). CellFormatter helper class allows to format cell value as text (waiting for other features).
  3. onDisposeCell method allows to release all used resources.
Below is a sample of the cell div and row div.
There are 2 points to mention:
  1. Each cell has margins and paddings with the content located inside the cell div. Remember, that your content is surrounded with these margins and paddings which are not under your direct control.
  2. Cell div occupies only the space it needs (display: inline-block). Consequently its height may be less than height of the row.
Similarly to Application customizer, Field Customizer can be configured with optional properties.

Command Set (ECB, Ribbon Custom Actions)

Command Sets let developers extend the command surfaces of SharePoint to add new actions, along with client-side code that can be used to implement behaviors. Previously, we knew such extensions as Custom Actions with Location set to Ribbon or ECB.

What can you do with this extension

You can add
  • custom buttons to the list's (document library's) command bar, or 
  • menu items to item's context menu
This buttons and menu items can contain custom code to execute some logic (just to remind: in new experience you could only add custom actions with URL as a command).
Provided entry points are onRefreshCommand and onExecute.
  1. onListViewUpdated method allows you to change the state of the command based on current state of the list view. The event parameter contains
    •  information about currently selected rows, 
    • commandId (this one is needed because you can have multiple commands in single Command Set) 
    • values of the command that can be changed: title, visible, ariaLabel, iconImageUrl.
  2. onExecute method is an entry point for command's execution. Use this method to implement all the logic related to the command. And, similarly to onListViewUpdated, you have access to commandId and selected rows through event parameter.

How to debug and deploy the extensions

The process of running and debugging the extensions differs from client side web parts because the execution is done on the O365 dev tenant pages, not on local workbench page.
I will not cover this part in the post but you can use the links below to get information on how to debug and deploy your extensions:
Debugging Application Customizer
Deploying Application Customizer to SharePoint
Debugging Field Customizer
Deploying Field Customizer to SharePoint
Debugging Command Set
Deploying Command Set to SharePoint

Resources

Here are the links to helpful resources related to the SharePoint Framework Extensions
Overview of SharePoint Framework Extensions (preview) - high-level overview of extensions by Microsoft and (in subsections) detailed description of creating your first extensions.
SharePoint Framework Extensions samples & tutorial materials - GitHub repository for the samples and materials related to the extensions.
Developer Preview Release Notes - basic information on what is included and how to get new bits.
Extensions RC Release Notes - here you can find the changes that were done in RC.
SharePoint Dev UserVoice - a place to share new feature requests.
SharePoint Framework Issues - a place to post issues/questions related to SharePoint Framework.
Office 365 Developer Program - here you can get Office 365 Dev tenant.
SharePoint Framework Overview - here you can find information about SharePoint Framework, Toolchain, "get started" kit, etc.
Office Dev Center Blogs - blog about Office 365 development.

That's it for now. In next posts I'll provide samples of each type of extensions with some details and how-tos.

Have fun!

No comments:

Post a Comment