Sp-dev-docs: Need a mechanism for provisioning SPFx web parts to pages

Created on 14 Dec 2016 · 15Comments · Source: SharePoint/sp-dev-docs

Expected or Desired Behavior

We need a way of ensuring SharePoint Framework web parts can be automatically added to pages in a templated way. Examples include:

As part of a site template (e.g. PnP remote provisioning schema)
As part of a page layout
..and so on

Consider the case where I am creating a "Contoso team site" template, and my organisation will create 10,000 sites per year. We need the home page to automatically have the right web parts with the right configuration - authors should not be required to add/configure these web parts themselves.

We previously had the AllUsersWebPart element to help us provision classic web parts, and we now need something similar for SPFx web parts.

Observed Behavior

SPFx web parts can currently only be added to pages manually (i.e. by editing each page individually).

Source

chrisobriensp

👍18

Most helpful comment

So for classic pages this shouldn't be an issue (shortly). We discovered an issue quite recently on how we persist that data on classic pages, and that's required a breaking change in the serialized data. Once we get the final schema sorted out and rolled out, we'll publish what it looks like. From that point, it looks like any other webpart, and you should be able to create them through any mechanism that we currently have (ie, the limited webpart manager).

One thing I would like to do is augment the workbench so that you can drop a webpart on to it, configure it, then get the class webpart serialized data displayed so you can copy/paste it into your code.

The modern pages are slightly different, in that the webpart configuration isn't stored in the webpart table, but in the content itself. We'll need to (at a minimum) document the format so that you can create the content appropriately, as well as document the rest of the structure of the page, so that you can create them with the right metadata to get things working.

patmill on 14 Dec 2016

👍3

All 15 comments

The inverse is true as well. Just as there needs to be a way to set the page content, there needs to be a way to read it. Should this be a separate issue or can it be tracked with this one?

douglasware on 14 Dec 2016

👍1

I'd also add that this capability (as an API) be provided to programmatically add a client web part to the workbench (both locally / O365 hosted).

_Scenario: full E2E automated testing of a web part._

andrewconnell on 14 Dec 2016

patmill on 14 Dec 2016

👍3

@andrewconnell - can you elaborate a bit about how you see that flow working?

patmill on 14 Dec 2016

@patmill - sure... when building any type of application, two types of testing: unit testing & end-to-end testing. The former tests specific methods, classes & service calls to name a few things. Just like we have today with gulp tests.

The next level is not just testing the code, but test an end-to-end scenario. For instance, think about a weather web part where you don't want the web part updating on every keypress in the property pane... so you make the property pane non-reactive. Ideally you would create a test that would ensure the APPLY button appeared on the page, or that the loading animation would show when fetching data from a slow service.

Sure, you can manually add the web part and visually spot check it but not great for a green/red build and CI.

Does that help?

andrewconnell on 14 Dec 2016

@andrewconnell - Sorry, I should have been more specific. What would the explicit flow look like for you from an API perspective? How would you program against the workbench? Would it be sufficient to create a modern page via API with the webpart you want in it?

I'm unsure of how programming against the workbench would work (at least in it's latest incarnation as an _layouts page).

patmill on 14 Dec 2016

@patmill - Ah... now I see what you're asking... thought you were asking for a scenario.

"Would it be sufficient to create a modern page via API with the web part you want in it?"

I'm not sure 100% but _I don't think so_... meaning I doubt anyone would leverage that for E2E. Why?

The way E2E testing is typically done with both React & Angular (ng1 & ng2) is using the Selenium WebDriver (Angular has a tool, Protractor, that leverages Selenium WebDriver so still same thing). This makes it easy to launch things both headless (or not) and instrument the page ("what's the value of this element's class?", "click this button", "fire that event on this element", etc). While I haven't yet dug into the details on how the local workbench is created / hosted, what I'd need to look at is to see if Selinum can launch/host the workbench. IMHO this would be the more preferred way of doing it, using mock data & services rather than live data & services.

Technically the scaffolding of E2E tests could authenticate with SharePoint, create a modern page, use the API you mention to add it to the page & then use some library to instrument the page. But that's not simple code to write and I would guess most wouldn't do it.

However, that's more the old way of doing client side dev E2E testing and not how devs have been building client side apps in the last few years with client side web frameworks.

andrewconnell on 14 Dec 2016

Will tenant-scoped SFPx app/web part install+trust be supported in future? This wasn't possible via the app catalog ("/_layouts/15/DeployTSApp.aspx" page) last time I checked, and an imported SPFx web part on a classic page didn't work without the app being installed manually from site contents.

zplume on 9 Jan 2017

As SPFx is in RC0, do we have any updates regarding provisioning a client web part on a either modern page or classic page? I found out when my customers adapt the O365 modern team site(O365 Group), they need a way to provisioning a modern page with custom client web parts as home page.

frankchen76 on 18 Jan 2017

While we wait for a supported API... here's a quick and dirty way that works with PnP PowerShell (only tested with the OOTB canvas webparts tho).

if($template -eq "Planner"){
    #Connect to templates site
    Connect-PnPOnline -Url https://tenant.sharepoint.com/sites/Template-Site -Credentials $mycreds

    $templatePage = Get-PnPListItem -List "Site Pages" -Query ("<View><Query><Where><Eq><FieldRef Name='Title'/><Value Type='Text'>" + $template + "</Value></Eq></Where></Query></View>")
    $canvasContent = $templatePage["CanvasContent1"]
    $updatedContent = $canvasContent -replace "_Title_", $title -replace "_SiteDescription_", $description -replace "_SiteOwner_", $siteOwner -replace 'https&#58;//_plannerurl_', $plannerUrl -replace "_SiteExpiry_", $siteExpiry

    #Connect to Target site
    Connect-PnPOnline -Url $siteUrl -Credentials $mycreds

    $homepage = Get-PnPListItem -List "Site Pages" -Id 1
    $homepage["CanvasContent1"] = $updatedContent
    $homepage.Update()
    Execute-PnPQuery
}

balbany on 19 Jan 2017

👍1

Now resolved - thanks SPFx team. The following links have info:

http://www.sharepointnutsandbolts.com/2017/03/provisioning-modern-pages-and-spfx-web-parts.html (blog article I wrote)
https://msdn.microsoft.com/en-us/pnp_articles/modern-experience-customizations-customize-pages#using-the-pnp-support-for-modern-pages-and-client-side-web-parts (MSDN article)

chrisobriensp on 20 Mar 2017

It's great, but it doesn't resolve the case when provision site programmatically and need to provision pages on the site with custom web parts... I think the case like create site programmatically and then manually add some apps... don't you think it sounds strange?

winperec on 27 Jun 2017

Hi @winperec - MS have said in recent PnP webcasts that they are currently working on APIs and features to allow deployment of SPFx apps - either on a site-by-site basis (programmatically) or as a 'once per tenant' deployment, which would allow you to fully automate deployment of SPFx web parts to pages (for example during remote site provisioning).

I raised an issue about needing tenant-scoped deployment here which is still open:
https://github.com/SharePoint/sp-dev-docs/issues/344

zplume on 27 Jun 2017

Is this possible to provision custom web parts using pnp remote provisioning now?

sirkot1 on 20 Dec 2017

Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: Issue List: Our approach to locked issues