By 20,034 total views, 5 views today
In this article, we will develop our first hello world SharePoint Framework Extensions 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: SharePoint Framework Extensions
- 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 – SharePoint Framework Extensions
In the SPFx framework, we can develop three types of client-side solution such as:
- WebPart
- Extension
- 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
-
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
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: SharePoint Framework Extensions
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
After sometimes, we can see that the SPFx application extension project – scaffolding is 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 – SharePoint Framework Extensions
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
}
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();
}
}
Code Explanation: SharePoint Framework Extensions
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"
}
}
}
}
}
}
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
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.
Download Source Code: SharePoint Framework Extensions
The above source code can be downloaded from here.
Summary: SharePoint Framework Extensions
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 summarize 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: Sharepoint Framework Tutorial
You may also like the below SharePoint SPFx articles:
- How to pass textbox entry in SPFx framework as a parameter – SharePoint Online
- Create list in SharePoint Online using SPFx (SharePoint Framework)
- SharePoint Online: Develop custom search web part using PnP JS and SharePoint Framework(SPFx)
- SharePoint Online: Use theme color in SharePoint SPFx framework web part
- SharePoint Online: CRUD operations using SPFx ReactJS framework
- SharePoint Online: CRUD operations using SPFx no javascript framework
- Develop your first hello world web part in sharepoint framework (SPFx)
- Understanding solution structure in SharePoint framework (SPFx)
- Create custom property in SharePoint Framework – SPFx web part pane
- Get list items from SharePoint using SPFx framework(No Javascript Framework)
- Custom search result page in SharePoint Online – SPFx PnP Modern Search solution
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 and write to the comment section. 🙂
Download SharePoint Online & Office 365 Administration eBook
Buy the premium version of SharePoint Online & Office 365 administration eBook from here:
Get the free demo PDF eBook from here:
Send download link to:
About Post Author
