Using SPFx build your first SharePoint Framework Extension - Hello World

Using SPFx build your first SharePoint Framework Extension – Hello World

No comments

 1,784 total views,  12 views today

In this article, we will develop our first hello world SharePoint Framework Extension using SPFx. Before that, a little recap about SPFx – SharePoint Framework (SPFx) Extensions are client-side components that run inside the context of a SharePoint page. We can deploy extensions project to SharePoint Online, and we can use modern JavaScript tools and libraries to build them. Let’s get started with the tutorial.

Key-Highlights: What you will learn from this article?

  • Introduction to application extension solution in the SPFx Framework
  • Create an extension project step by step process – scaffolding process
  • Analysis of code file structure
  • How to debug the SPFx Application Customizer project in SharePoint Online?
  • Demo – Verification of Application Customizer SPFx project from the SharePoint Online page.

Introduction to application extension solution in the SPFx Framework

In the SPFx framework, we can develop three types of client-side solution such as:

  1. WebPart
  2. Extension
  3. Library

As we can see the “Extension” type is one among them. Each type of above project type has its own need and scope while it comes to customizing the SharePoint solution. For example, using the web part we can display the SharePoint content in a specific area of the page, using the “Extension” type we can customize the site level object such as site header, footer, navigation, etc. and using the “Library” type project we can customize the list/library, view, etc.

Create an extension project step by step process – scaffolding process

  1. Create a new project directory (folder) in your specified location using the below command:

C:\Temp\SPFx\Application Extension>md HelloWorld_App_Extension

2. Go to the project directory using the below command

cd HelloWorld_App_Extension

Create project directory for SPFx Application extension project
Create a project directory for SPFx Application extension project

3. Run the yo @microsoft/sharepoint command to generate the extension project.

yo @microsoft/sharepoint

C:\Temp\SPFx\Application Extension\HelloWorld_App_Extension>yo @microsoft/sharepoint

4. Pass the input parameters as prompts:

Let's create a new SharePoint solution.
? What is your solution name? Hello_World_App_Extension
? Which baseline packages do you want to target for your component(s)? SharePoint Online only (latest)
? Where do you want to place the files? Use the current folder
Found npm version 6.14.7
? Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without
running any feature deployment or adding apps in sites? No
? Will the components in the solution require permissions to access web APIs that are unique and not shared with other c
omponents in the tenant? No
? Which type of client-side component to create? Extension
? Which type of client-side extension to create? (Use arrow keys)
> Application Customizer
Field Customizer
ListView Command Set
Add new Application Customizer to solution hello-world-app-extension.
? What is your Application Customizer name? Hello_World_Application_Customizer
SPFx Application extension project - yo microsoft-sharepoint
SPFx Application extension project – yo microsoft-sharepoint

 

After sometimes, we can see that the SPFx application extension project – scaffolding is completed.

SPFx Application extension project - scaffolding completed
SPFx Application extension project – scaffolding completed

 

Note:

While passing the name of the extension, try to keep length within 40 characters – in the manifest JSON file an alias name is registered. Nevertheless, if you face any issues during running the gulp serve –nobrowser command, we can resolve this by updating the alias entry afterward.

 

5. Open the project in visual studio editor

Run the “Code .” command to open the project in visual studio editor.

C:\Temp\SPFx\Application Extension\HelloWorld_App_Extension>code .

6. Analysis of code file structure

Open the HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json file

Go to the below path to open the HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json file.

./src/extensions/helloWorldApplicationCustomizer/HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json

This file defines your extension type and a unique identifier for your extension. We will need this ID later when we debug and deploy the extension to SharePoint Online.

HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json content:
{

  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-extension-manifest.schema.json",

  "id": "5fbb5b79-2843-4e48-83e9-c5699ac74edb",

  "alias": "HelloWorldApplicationCustomizerApplicati",

  "componentType": "Extension",

  "extensionType": "ApplicationCustomizer",

  // The "*" signifies that the version should be taken from the package.json

  "version": "*",

  "manifestVersion": 2,

  // If true, the component can only be installed on sites where Custom Script is allowed.

  // Components that allow authors to embed arbitrary script code should set this to true.

  // https://support.office.com/en-us/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f

  "requiresCustomScript": false

}

 

Manifest.json file in the SPFx application customizer project
Manifest.json file in the SPFx application customizer project

Notes:

  • The “*” signifies that the version should be taken from the package.json.
  • If true, the component can only be installed on sites where Custom Script is allowed.

 

6. Open the HelloWorldApplicationCustomizerApplicationCustomizer.ts file

Go to the below path to open the HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json file.

./src/extensions/helloWorldApplicationCustomizer/HelloWorldApplicationCustomizerApplicationCustomizer.ts

This file defines your extension type and a unique identifier for your extension. We will need this ID later when we debug and deploy the extension to SharePoint Online.

HelloWorldApplicationCustomizerApplicationCustomizer.ts file content:

import { override } from '@microsoft/decorators';

import { Log } from '@microsoft/sp-core-library';

import {

  BaseApplicationCustomizer

} from '@microsoft/sp-application-base';

import { Dialog } from '@microsoft/sp-dialog';

import * as strings from 'HelloWorldApplicationCustomizerApplicationCustomizerStrings';

const LOG_SOURCE: string = 'HelloWorldApplicationCustomizerApplicationCustomizer';

/**

 * If your command set uses the ClientSideComponentProperties JSON input,

 * it will be deserialized into the BaseExtension.properties object.

 * You can define an interface to describe it.

 */

export interface IHelloWorldApplicationCustomizerApplicationCustomizerProperties

{

  // This is an example; replace with your own property

  testMessage: string;

}

/** A Custom Action which can be run during execution of a Client Side Application */

export default class HelloWorldApplicationCustomizerApplicationCustomizer

  extends BaseApplicationCustomizer<IHelloWorldApplicationCustomizerApplicationCustomizerProperties> {

  @override

  public onInit(): Promise<void>

   {

    Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);

    let message: string = this.properties.testMessage;

    if (!message) {

      message = '(No properties were provided.)';

    }

    Dialog.alert(`Hello from ${strings.Title}:\n\n${message}`);

    return Promise.resolve();

  }

}
HelloWorldApplicationCustomizerApplicationCustomizer.ts file in the SPFx application customizer project
HelloWorldApplicationCustomizerApplicationCustomizer.ts file in the SPFx application customizer project

Code Explanation:

Here we can see that the base class for the Application Customizer is imported from the HelloWorldApplicationCustomizerApplicationCustomizer.ts file in the SPFx application customizer project, which contains the SharePoint framework code required by the Application Customizer.

The logic for the Application Customizer is contained in the onInit() method, which is called when the client-side extension is first activated on the page. This event occurs after this.context and this.properties are assigned.

The class constructor is called at an early stage when this.context and this.properties are undefined. Custom initiation logic is not supported here.

7. How to debug the SPFx Application Customizer project in SharePoint Online?

Now, this is the time to debug and test our application customizer project from the SharePoint Online site, so, let’s get started on how to debug it.

Well, the way we test the SPFx web part project in local workbench, we cannot use it to test the SharePoint Framework Extensions project. However, you don’t need to deploy your customization to the app catalog site to test the solution, which makes the debugging experience simple and efficient.

7.1 Open the ./config/serve.json file.

Open the serve.json file from the config/serve.json path.

{

  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",

  "port": 4321,

  "https": true,

  "serveConfigurations": {

    "default": {

      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",

      "customActions": {

        "5fbb5b79-2843-4e48-83e9-c5699ac74edb": {

          "location": "ClientSideExtension.ApplicationCustomizer",

          "properties": {

            "testMessage": "Test message"

          }

        }

      }

    },

    "helloWorldApplicationCustomizer": {

      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",

      "customActions": {

        "5fbb5b79-2843-4e48-83e9-c5699ac74edb": {

          "location": "ClientSideExtension.ApplicationCustomizer",

          "properties": {

            "testMessage": "Test message"

          }

        }

      }

    }

  }

}
serve.json file in the SPFx application customizer project
serve.json file in the SPFx application customizer project

Notes:

  • We can see that pageUrl is a default Contoso URL, we need to update this URL with our SharePoint Online site URL where we want to test this.
  • GUID used in the above JSON file is defined by the SPFx extension project, which is available in this file HelloWorldApplicationCustomizerApplicationCustomizer.manifest.json file.

Demo – Verification of Application Customizer SPFx project from the SharePoint Online page.

Let’s have our Site Page URL ready from our tenant:

Page URL: https://globalsharepoint2020.sharepoint.com/sites/CustomSearchRND/SitePages/SPFxAppCustomizerTest.aspx

Allow debug scripts in SPFx Application Extension Customizer Project
Allow debug scripts in SPFx Application Extension Customizer Project

Click on the “Load debug scripts” button, then we can see an alert – “Hello from HelloWorldApplicationCustomizerApplicationCustomizer: Test message” which has come from the SPFx application customizer project.

Alert from SPFx Customizer Application Project
Alert from SPFx Customizer Application Project

Download Source Code:

The above source code can be downloaded from here.

Summary:

Thus, in this article, we have learned how to create an extension type project in SPFx and debug from the SharePoint Online page, we can summary the tutorial as below:

  • Introduction to application extension solution in the SPFx Framework
  • Create an extension project step by step process – scaffolding process
  • Analysis of code file structure
  • How to debug the SPFx Application Customizer project in SharePoint Online?
  • Demo – Verification of Application Customizer SPFx project from the SharePoint Online page.

See Also

You may also like the below SharePoint SPFx articles:

Hope you have enjoyed reading this article and helped you. If you like to appreciate our efforts, please do share this with your friends and colleagues. 🙂

Free download SharePoint Online & Office 365 Administration eBook(238 Pages)

Get the PDF eBook from here:


 
FREE DOWNLOAD

Send download link to:

Subscribe to get exclusive content and recommendations every month. You can unsubscribe anytime.