SharePoint modern page tutorial: an SPFX Tour sample WebPart

Update: I was mentioned during SharePoint Dev Weekly - Episode 61 – 26th of November 2019
If you want you can see the registration here :)

Update 2: During December, 19 2020 SharePoint Framework Community Call   I made a demo of my contribution, here you can find the registration :) 

Hi guys!
Today we’ll talk about a new SPFx sample webpart I made using SharePoint Framework! 

General needs

Usually, SharePoint sites are user-friendly, especially modern ones. Sometimes though, especially in the context of adoption a new site, like a new Modern Intranet, it is good to offer users the possibility of having a page guide, a tour, a tutorial, so that they do not feel lost like confused John Travolta

To improve site adoption, you could create a video guide or well-explained documentation. However, some users do not have the time to read the documentation or to watch the video, they would just like to use the new site! For this type of end-users (most of them) you can create a dynamic tour while learning to use the new Intranet based on SharePoint Online.
There are lots of really cool plugin, using react too. I choose to use ReactTourJS.
Another package I decide to use is @pnp/spfx-property-controls a collection of reusable property pane controls for the SharePoint Framework solutions. In a particular way, I decided to try PropertyFieldCollectionData control

SPFx Tour WebPart in action!

Let’s look at how it works, applied to this really cool site The Landing taken from SharePoint look book sample!

When you start the tour, a modal will be displayed, with a description of the highlighted area, and you can go to the next step or go back, thus navigating inside the page.
The user will see the descriptions and will have the opportunity to preview the advice that the publisher thought for him.

SPFx Tour WebPart configuration

The WebPart property pane allows you to:

• Choice the WebPart from a list of all WebParts on the current page
• specify a descriptive text
• specify the sorting, according to which it will be shown in the tutorial
• enable or not the step within the tour

Code deep-dive

The solution is pushed in my GitHub repository, but I would like to focus on some snippets.

How to retrieve all SPFx WebPart in the current page

  public async GetAllWebpart(): Promise<any[]> {
    // page file
    const file = sp.web.getFileByServerRelativePath(this.context.pageContext.site.serverRequestPath);

    const page = await ClientSidePage.fromFile(file);

    const wpData: any[] = [];

   page.sections.forEach(section => {
      section.columns.forEach(column => {
        column.controls.forEach(control => {
          var wpName = {}
          var wp = {};
          //FIX: check if webPartData are available, in Text Webpart is undefined
          if (control.data.webPartData != undefined) {
            wpName = `sec[${section.order}] col[${column.order}] - ${control.data.webPartData.title}`;
            wp = { text: wpName, key: control.data.webPartData.instanceId };
            wpData.push(wp);
          } else {
            wpName = `sec[${section.order}] col[${column.order}] - "Webpart"`;
            wp = { text: wpName, key: control.data.id };
          }
          wpData.push(wp);

        });

      });
    });
    return wpData;
  }

How to customize @pnp/spfx-property-controls - PropertyFieldCollectionData with a textarea

 {
                      id: "StepDescription",
                      title: "Step Description",
                      type: CustomCollectionFieldType.custom,
                      onCustomRender: (field, value, onUpdate, item, itemId) => {
                        return (
                          React.createElement("div", null,
                            React.createElement("textarea",
                              {
                                style: { width: "600px", height: "100px" },
                                placeholder:"Step description",
                                key: itemId,
                                value: value,
                                onChange: (event: React.FormEvent<HTMLTextAreaElement>) => {
                                  console.log(event);
                                  onUpdate(field.id, event.currentTarget.value);
                                }
                              })
                          )
                        );
                      }
                    },

To locate the WebPart, ReactTourJS needs a selector. I used data-sp-feature-instance-id data property associated with the WebPart instance id

  public static getTourSteps(settings: any[]): any[] {

    var result: any[] = new Array<any>();

    if (settings != undefined) {
      settings.forEach(ele => {
        if (ele.Enabled) {
          result.push(
            {
              selector: '[data-sp-feature-instance-id=\'' + ele.WebPart + '\']',
              content: ele.StepDescription
            });
        }
      });

    }
    return result;
  }

And it is all from my side 🙂

I hope you enjoy my new code contribution!
Cheers
Federico