Single Page Application (SPA) is a paradigm to create modern web applications where the information is presented to the user through a single HTML page. This ensures that the sites are more responsive and closely replicate a desktop application or native app. A SPA retrieves all the application’s code such as HTML, JavaScript, and CSS on the initial load. Alternatively, depending on the user activity or affecting events, it may load resources dynamically in response to that update.
The Microsoft SharePoint interface shows pages built from several components which are called AppParts, these are originated from different sources built during runtime.
Figure 1. AppParts in a default page of SharePoint Online.
Until early 2019, it wasn’t possible to install one single AppPart filling the complete page’s real-state in SharePoint and simulate, somehow, the behavior of SPA sites. However, since the introduction of version 1.7 of the SharePoint Framework (SPFx), it’s now possible to configure SharePoint and the AppParts so we can carry out this task. At the time of writing this article, this option is only available for SharePoint Online, not for SharePoint Server. Nonetheless, it’s certainly a possibility that Microsoft may add this option to the Server version in a future Service Pack.
Using Single AppParts pages in SharePoint is important because it makes it possible to create: more complex AppParts, a filled page area, more controls and visual elements inside it, and, at the same time, enriching the user experience.
The process to create a Single AppPart page is a two steps process: create the SPFx component and configure it to fill the complete working area and configure the SharePoint page to render it consequently.
Create the SPFx AppPart
Initially, the creation of an SPFx AppPart for a Single AppPart page is similar to that of an AppPart. Microsoft offers extended information about the development of SPFx AppParts and the creation of a development environment on their documentation site.
Step 1 – Here, we need to use Yeoman, the tool used to generate SPFx projects, to scaffold a new AppPart for SharePoint. Ensure that you choose SharePoint Online only (latest) as the environment you want to use and select the client-side component type for the WebPart you want to create. You should then see a HelloWorld AppPart that can be run in the local Workbench gulp serve.
Figure 2. Running the default SPFx AppPart in the local Workbench.
Step 2 – Open the file ../src/webparts/helloWorld/HelloWorldWebPart.manifest.json using your code editor, for example, Visual Studio Code. Search for the supportedHosts section and then add a new value called SharePointFullPage as shown below.
Figure 3. Adding the support for full page in the configuration file.
Step 3 – Open the file “../src/webparts/helloWorld/HelloWorldWebPart.manifest.scss” and comment out using two backslash characters (“//”), as indicated in Figure 4. the max-width attribute. This is not required by the Single AppPart Page, but it will show the AppPart using the full page-width when it is hosted in SharePoint.
Figure 4. Configuring the styles to show the AppPart using the full width of the page.
Install the AppPart and use it on a page
Step 4 – Compile the AppPart gulp bundle –ship and follow the instructions in the Microsoft documentation to create and compile SPFx AppParts, and then generate its deployment package gulp package-solution –ship.
Step 5 – Open the SharePoint Catalog site and upload the AppPart package to the Apps for SharePoint library. Use the Make this solution available to all sites in the organization option to ensure that the AppPart will be immediately available for all site collections.
Figure 5. The AppPart installed in the SharePoint Catalog.
Step 6 – Create a new Blank page in one of the SharePoint site collections. Open the page and install the AppPart. It will behave like a normal AppPart, which means, it will be shown as one of the AppParts that can be installed in a zone and column of the page. The only difference is that the AppPart will use the full width of the column because we changed this option in the CSS file of the part.
Figure 6. The AppPart installed in a normal SharePoint page
Configure the page to become a Single AppPart Page
Although Microsoft describes different ways to configure SharePoint to make the page a Single AppPart Page (using JavaScript or the SharePoint CLI), the best way is using PowerShell PnP. Patterns and Practices for SharePoint (PnP) which is an Open Source initiative hosted in GitHub. This is closely monitored by Microsoft to enhance the SharePoint object models and PowerShell accessibility, filling the gaps that Microsoft should have done natively but never did.
Step 7 – To use the PowerShell PnP module, install it first, open a PowerShell console as Administrator and run the following command:
Install-Module -Name SharePointPnPPowerShellOnline
Step 8 – To log in to Office 365, use the next command and provide your credentials when asked. Replace [domain] and [SiteName]” with the name of your Office 365 domain and site collection name:
Connect-PnPOnline -Url "https://[domain].sharepoint.com/sites/[SiteName]"
Step 9 – Then, run the following script. Change the value of “[NamePage.aspx]” to the correct one. The first command must be in one line text.
$myPage = Get-PnPListItem -List "Site Pages" -Query "<View><Query><Where><Eq><FieldRef Name='FileLeafRef'/><Value Type='Text'>[NamePage.aspx]</Value></Eq></Where></Query></View>" $myPage["PageLayoutType"] = "SingleWebPartAppPage" $myPage.Update() Invoke-PnPQuery
“SingleWebPartAppPage” is the property that will convert the page to a Single AppPart page.
Step 10 – Go back to the page and refresh it.
Figure 7. The AppPart configured as full page in a SharePoint page
As you can see, the complete command bar at the top of the page and the header of the page are invisible now.
Step 11 – If you change the header of the page to Compact from the Settings in the Change the look and Header options, and remove the Quick Launch menu, the complete interface of the page will be available for the AppPart, making it look like the design of a SPA:
Figure 8. The AppPart used as full page with the quick launch menu removed
Step 12 – To return the page to the normal rendering, change PageLayoutType property in the script to Article, and run it again:
$myPage["PageLayoutType"] = "Article"
There are a few things you should note about the Single AppPart Pages in SharePoint:
- These pages are made to host only one AppPart
- If you install more than one AppPart on the page and then convert it to Single AppPart Page, only the first AppPart will be rendered. The other AppParts are only hidden and will be visible again if the page is configured back to “Article”
- Single AppPart Pages can also be used by the ‘out of the box’ AppParts
- The configuration panel of the AppParts is fully useable for both, custom and ‘out of the box’ AppParts
- There seems to be a bug in these pages for users with read-only rights: the new layout disappears, and the page is rendered as a normal SharePoint page. The bug is reported to Microsoft.
As a conclusion, we can say that the Single AppPart pages in SharePoint are a useful option to create SPFx AppParts that need to use the complete real-state of SharePoint. In this way, the designer and developer can create more rich and useable interfaces. Additionally, the needed changes to implement it are not intrusive and easy to recognize.
