Repository files navigation

Sample SPFx webpart built using React, also illustrating different scenarios to fetch data from SP REST, PnP, MS Graph and Mockup data.

This webpart illustrates the following concepts on top of the SharePoint Framework:

• Using React for building SharePoint Framework client-side webparts
• Using Office UI Fabric React styles for building user experience consistent with SharePoint and Office
• Communicating with the Microsoft Graph, SharePoint REST API and PnP API
• Passing webpart properties to React components
• Using Chart.js plugin to display chart indicators

• Set up development environment

git clone the reponpm inpm i -g gulpgulp

This package produces the following:

• lib/* - intermediate-stage commonjs build artifacts
• dist/* - the bundled script, along with other resources
• deploy/* - all resources which should be uploaded to a CDN.

• gulp trust-dev-cert

  Command to install the developer certificate for building your custom solutions easily with HTTPS endpoint.

• gulp clean

  Command to clear the temporary build folders and files created in the solution. Some of the folders cleaned up during the process aretemp/ anddist/.

• gulp serve

  This command executes a series of gulp tasks to create a local, node-based HTTPS server onlocalhost:4321 and launches your default browser to preview webparts from your local dev environment. Note: if you see issues with the certificate in the browser, please rungulp trust-dev-cert command. The minified assets can be found under thetemp\deploy directory.

• gulp bundle

  Command to build a bundle of your solution.

• gulp bundle --ship

  This builds the minified assets required to upload to the CDN provider. The--ship indicates the build tool to build for distribution.

• gulp package-solution

  This command packages one or more client-side component manifests, such as webparts, along with the feature XML files referenced in thepackage-solution.json configuration file.

• gulp package-solution --ship

  Same as the previous command but with--ship flag to package minified versions of your components.

• gulp serve --locale=es-es

  To specify the locale to be used by the local SharePoint workbench.More info

1. Install TSLint extension on VSCode
2. Add atslint.json file on the root of the project to tell the extension to get its rules from theconfig folder:

   {rulesDirectory:'./config'}

1. Install Prettier extension:ext install prettier-vscode

2. Add a.prettierrc file to the root of the project to tell the extension to use the following prettier rules:

   {singleQuote:true}

   NOTE: To avoid rule conflicts between TSLint and Prettier follow below steps.

3. Install some packages and update TSLint rules:

   • npm install --save-dev tslint tslint-config-prettier tslint-eslint-rules tslint-react
   • Update./config/tslint.json file to extend the default linting functionality:

   "lintConfig":{"extends":["tslint:latest","tslint-react","tslint-eslint-rules","tslint-config-prettier"],"rules":{// ... other rules omitted for brevity"quotemark":[true,"single","jsx-double"]}}

1. Install packages:npm install --save-dev husky lint-staged prettier
2. Edit thepackage.json file to configure the git hooks as following:

"scripts":{// ... other scripts omitted for brevity"precommit":"lint-staged",},"lint-staged":{"*.{json,css,scss,md}":["prettier --write","git add"],"*.{js,ts,tsx}":["tslint --fix","prettier --single-quote --parser typescript --write","git add"]},

3. Now, every timegit commit command is executed, the staged files will be formatted according to tslint and prettier rules configured.

Onsrc/EmployeePerformanceAppWebPart.manifest.json file, update following properties:

• Group GUID for modern experience:

"groupId":"1bc7927e-4a5e-4520-b540-71305c79c20a",// GUID for Planning and process

• Group name for classic experience:

"group":{"default":"[Group-name]",},

NOTE: This icon only applies to modern sites.

1. The easiest way to configure a webpart icon is to use an icon name fromOffice UI Fabric
2. Onsrc/EmployeePerformanceAppWebPart.manifest.json file, update following property:

"officeFabricIconFontName":"[icon-name]",

NOTE: This icon only applies to classic sites.

1. Get an image icon with 96px to 96px dimension.
2. Upload the icon to thesharepoint/images folder
3. Onconfig/package-solution.json file, update the following property to reference the new icon:

"iconPath":"images/[icon-name].png",

This sample webpart provide four different lists to a SharePoint site

1. Add SP List schemas inside thesharepoint/assets folder
2. Add a "features" option onconfig/package-solution.json file to reference the lists schemas as follows:

"solution":{// other attributes omitted for brevity"features":[{"title":"employee-performance-app-assets","description":"List assets for employee performance app","id":"368d2b60-be42-4505-986a-5f775c922780","version":"1.0.0.0","assets":{"elementManifests":["elements.xml"],"elementFiles":["employeesListSchema.xml","achievementsListSchema.xml","earnedAchievementsListSchema.xml","performanceSkillsListSchema.xml"]}}],}

For more information on how to provision SP assets, please read carefully thisguide and these samples:sample 1,sample 2.

1. For localization string resources declare the property names of the strings inside the[webpart]/loc/mystrings.d.ts file, example:

declareinterfaceIEmployeePerformanceAppWebPartStrings{PropertyPaneDescription:string;CardsMenuLabel:string;InformationMenuLabel:string;AchievementsMenuLabel:string;PerformanceMenuLabel:string;DataProviderGroupName:string;}

2. Add the resources files inside the[webpart]/loc folder using LCID named files. example:

   • en-us.js: For english
   • es-es.js: For spanish

3. To use the string resources import them as following:

import*asstringsfrom'EmployeePerformanceAppWebPartStrings';

Each folder purpose is described below:

For more recomendations on how to properly scaffold the project, please read thisdocument.

This webpart uses different data providers to fetch data from SharePoint:

This property indicates the environment where the SPFx is running and it is pretty useful if the webpart needs to behave different depending the running environment, it has four types and values:

• 0 = Test
• 1 = Local
• 2 = SharePoint
• 3 = ClassicSharePoint

By default the package template comes with two debug configurations, on for the local workbench and the other onw for the hosted workbench (online).

To debug the code on thelocal workbench, follow the next steps:

1. Add a breakpoint
2. Run this command on the terminal:

gulp serve --nobrowser

3. PressF5 to start the debbuging option on VSCode
4. On the local workbench, add the webpart to the page

To debug the code on thehosted workbench, follow the next steps:

1. Update theurl property on the.vscode/launch.json file

  {    "name": "Hosted workbench",    "type": "chrome",    "request": "launch",    "url": "https://[SharePoint-Site]/_layouts/workbench.aspx",    ... // other properties omitted for brevity  }

2. Add a breakpoint
3. Run this command on the terminal:

gulp serve --nobrowser

3. PressF5 to start the debbuging option on VSCode
4. On the hosted workbench, add the webpart to the page

This webpart shows how to render a choice property and also to disable the reactive updates form the proerty pane by overridingdisableReactivePropertyChanges method:

// Override this method to disable reactive property paneprotectedgetdisableReactivePropertyChanges(): boolean{returntrue;}protectedgetPropertyPaneConfiguration():IPropertyPaneConfiguration{return{pages:[{header:{description:strings.PropertyPaneDescription},groups:[{groupName:strings.DataProviderGroupName,groupFields:[PropertyPaneChoiceGroup('dataProvider',{options:[{key:DataProvider.MockData,text:'Mock Data'},{key:DataProvider.MSGraph,text:'MS Graph'},{key:DataProvider.PnP,text:'PnP API'},{key:DataProvider.REST,text:'REST Service'}]})]}]}]};}}

To update the DataProvider of the webpart, while running the webpart open the property pane, select one data provider to fetch the information and finally click on "Apply" button.

For more information regarding property pane configuration gohere

1. Bundle the project to verify everything will complie properly by running the following command using--ship argument to bundle it in production mode:

  gulp bundle --ship

2. Package the project by running the following command using--ship argument to package it in production mode:

  gulp package-solution --ship

3. Upload the.ppkg file to the app catalog on your tenant
4. Install the app on your site
5. Add the webpart to a SharePoint page

THIS CODE IS PROVIDEDAS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.