Provisioning SPFx WebPart assets: adding a page with your webpart embedded to it

Question

As far as I can see it should be doable to create a package which can automatically, once the app is added to your site, to create a page and embed the webpart on it - as described here: https://github.com/SharePoint/sp-dev-fx-webparts/tree/master/samples/react-provision-assets.

So far I haven't figured out which data exactly about my web part I need to enter on the page configuration file, and where:

https://github.com/SharePoint/sp-dev-fx-webparts/blob/master/samples/react-provision-assets/sharepoint/assets/WebPartSitePage.aspx

I experimented with the ID located after this tag: < mso:ClientSideApplicationId msdt:dt="string" >, but it doesn't seem to work.

The same question seems to have been asked a lot of times here, on StackExchange, but regarding older provisioning methodologies. I am interested in the one, described unter the mentioned link.

Answer 1

TL;DR

You're on the right track, but look at the mso:CanvasContent1 tag instead!

The real answer

It looks like the bulk of your configuration would be in the <mso:CanvasContent1 ...> line. Note the contents of the tag is encoded. Here it is, decoded and formatted as HTML:

<mso:CanvasContent1 msdt:dt="string">
  <div>
    <div
      data-sp-canvascontrol=""
      data-sp-canvasdataversion="1.0"
      data-sp-controldata="&amp;#123;&amp;quot;controlType&amp;quot;&amp;#58;3,&amp;quot;webPartId&amp;quot;&amp;#58;&amp;quot;e89b5ad5-9ab5-4730-a66b-e1f68994598c&amp;quot;,&amp;quot;id&amp;quot;&amp;#58;&amp;quot;8bba86eb-3174-4917-b2b8-417af1102351&amp;quot;&amp;#125;"
    >
      <div
        data-sp-webpart=""
        data-sp-webpartdataversion="1.0"
        data-sp-webpartdata="&amp;#123;&amp;quot;id&amp;quot;&amp;#58;&amp;quot;e89b5ad5-9ab5-4730-a66b-e1f68994598c&amp;quot;,&amp;quot;instanceId&amp;quot;&amp;#58;&amp;quot;8bba86eb-3174-4917-b2b8-417af1102351&amp;quot;,&amp;quot;title&amp;quot;&amp;#58;&amp;quot;ReactProvisionAssets&amp;quot;,&amp;quot;description&amp;quot;&amp;#58;&amp;quot;ReactProvisionAssets description&amp;quot;,&amp;quot;dataVersion&amp;quot;&amp;#58;&amp;quot;1.0&amp;quot;,&amp;quot;properties&amp;quot;&amp;#58;&amp;#123;&amp;quot;description&amp;quot;&amp;#58;&amp;quot;ReactProvisionAssets&amp;quot;&amp;#125;&amp;#125;"
      >
        <div data-sp-componentid="">e89b5ad5-9ab5-4730-a66b-e1f68994598c</div>
        <div data-sp-htmlproperties=""></div>
      </div>
    </div>
  </div>
</mso:CanvasContent1>

Note these three things:

1. The data-sp-componentid attribute should hold the GUID of the web part you want to mount. Make sure to paste that in at some point (it's in the manifest.json).
2. The data-sp-controldata attribute is an HTML-encoded JSON string, including some logistical identifiers for the web part you want to mount.
3. The data-sp-webpartdata attribute is another HTML-encoded JSON string, including more nitty-gritty info (property values, etc.) about the web part.

For (2) and (3), here is the JSON structure of both attributes, decoded, formatted, and commented with where you might get the values:

"data-sp-controldata": {
    "controlType": 3, // Leave as-is
    "webPartId": "e89b5ad5-9ab5-4730-a66b-e1f68994598c", // ID of your web part, as found in the manifest.json
    "id": "8bba86eb-3174-4917-b2b8-417af1102351" // Generate a new GUID here for the "instance" of the web part
},
"data-sp-webpartdata": {
    "id": "e89b5ad5-9ab5-4730-a66b-e1f68994598c", // ID of your web part, again
    "instanceId": "8bba86eb-3174-4917-b2b8-417af1102351", // Copy the new GUID you generated above in "id"
    "title": "ReactProvisionAssets", // Copy the "title" as found under preconfiguredEntries in the manifest.json
    "description": "ReactProvisionAssets description", // Copy the "description", also under preconfiguredEntries
    "dataVersion": "1.0", // Leave as-is
    "properties": { // Copy the "properties" in preconfiguredEntries here
        "description": "ReactProvisionAssets"
    }
}

Basically you'd have to fill these fields out with your own values. Once you have figured all that out...

1. Stringify the JSON for each of data-sp-controldata and data-sp-webpartdata (note: starting from the 2nd level of braces).
2. Re-encode the special characters { ({), } (}), : (:), " ("), and & (&) in the JSON.
3. Paste the strings back into data-sp-controldata and data-sp-webpartdata respectively in the mso:CanvasContent1.
4. Re-encode the characters < (<), > (>), and " (") in the HTML.
5. Finally, paste the mso:CanvasContent1 back into your WebPartSitePage.aspx.

The easy way

Well gee, all of this encoding and decoding sounds annoying and error-prone. Isn't there some easier way of doing this?

Yes! You'll need to be able to deploy your SPFx solution first, though. Add the web part to a Site Page on a test site somewhere. Then, grab the ASPX file for that page somehow...

• Using REST API: /_api/web/getFileByServerRelativeUrl('/sites/<PATH>/<TO>/<THE>/SitePages/MyPage.aspx')/$value
• Using SharePoint Designer: open the ASPX page for editing, and copy its contents
• ... Other options are probably available

Finally, copy the ASPX code over into your SPFx solution. Tested and worked much more easily than the above!