SharePoint Wiki Page with Web Parts Pattern for Custom UI

In my previous post I used a scoring system to come up with an answer to the question: What is the most ideal type of page to use when customizing SharePoint? Somewhat surprisingly, the answer based on my criteria is a SharePoint Wiki Page. A wiki page which has the advantage because all wiki pages are served from a shared template instead of being actual files. Creating a wiki page doesn’t create a custom ASPX page that requires maintenance. By relying on the central template, the structure and features of a wiki page stays up to date as SharePoint evolves.

In this post I will cover one of the patterns for custom UI based on wiki pages we use in our apps here at InstantQuick: Wiki Page with Web Parts. This pattern is best if we want to allow the owners of the target site to modify the solution after it is deployed. It does not require a provider host and works when an add-in is fully contained in SharePoint. You can see this design pattern in action in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework.

Wiki Page with Web Parts Pattern

This pattern is the easiest to follow because you can implement it using nothing but SharePoint and a text editor like notepad. The pattern consists of a wiki page, the default page type in a Team site, and one or more Content Editor or Page Viewer Web Parts that load the custom solution. Logically, the pattern looks like this:

The pattern is simple, but one important rule is that a customization’s appearance and behavior should depend only on the scripts, style sheets, and other resources included in the customization – not on the parent document’s or its related resources. Following this rule gives your customization the best chance for a maintenance free future as the SharePoint platform evolves.

The easiest way to enforce this rule is to refine the pattern to contain the customization in an iframe.

The iframe creates a new document that allows the customization to work in isolation from the parent document. In this version of the pattern the app must be contained in an ASPX page. The default permissive file handling settings will cause the browser to download html files instead of rendering the html in a frame. The file extension prevents the download.

The container ASPX used in in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework is shown below. As you can see it does not contain any actual server side code.

What is the most ideal type of page to use when customizing SharePoint?

Very few platforms offer the range of customization options that SharePoint offers. The menu is huge! How does one go about the task of choosing the most ideal way to do anything?

In this post I am going to tackle one of the most fundamental choices everyone faces – What is the best way to make a custom web page for a SharePoint customization?

For this contest I am including only options that do not require third-party solutions and that work on-premises and in SharePoint Online.

The Contestants

The nominees for the best way to make a custom SharePoint web page are:

  • Custom SharePoint ASPX Page
  • External / Provider Hosted UI
  • Publishing Page
  • SharePoint App-in Web Hosted UI
  • Traditional SharePoint Web Part Page
  • SharePoint Wiki Page

Evaluation Criteria

Not long ago I wrote a post describing 8 Characteristics of an Ideal SharePoint Customization. I will judge each of the options based on these ideals, but to be as objective as possible pretend that each option meets the first and last ideals: It meets the needs of the people who use it without limitations imposed by the platform and It is manageable and governable.

In other words, I will try to do this without introducing hypothetical requirements or assuming anything about the ability of an organization to support and maintain the solution. This will let me answer the question of the most ideal option in general.

In real life, with real requirements and real people, you should always evaluate whether each option meets the needs of the people who use it without limitations imposed by the platform and if you can manage and govern the result. Sometimes the actual requirements will determine or limit your options. For example, if you are building a site using SharePoint’s publishing features, you will use Publishing Pages.

Finally, because this is specifically about pages the ideal, Runtime or configuration faults in a customization can only impact the customization, generally doesn’t apply; we use different tools to break whole sites.

That leaves five remaining ideals we can use to weigh the options.

  1. It doesn’t interfere with the operation of the underlying platform
  2. It uses SharePoint functionality as much as possible
  3. It depends on things other than SharePoint as little as possible
  4. It cedes runtime control to SharePoint as little as possible
  5. The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Scoring

Here is a place where my ideals could use some refining, because ‘as little as possible’ is subjective. However, I am comparing each option to each ideal and saying ‘true’ or ‘false’ without giving partial credit. The one with the most true’s wins the prize.

Summary

 

A

B

C

D

E

Custom SharePoint ASPX Page

 

X

X

   

External / Provider Hosted UI

X

   

X

X

Publishing Page

 

X

X

   

SharePoint App-in Web Hosted UI

   

X

   

Traditional SharePoint Web Part Page

 

X

X

   

SharePoint Wiki Page

X

X

X

 

X

 

Custom SharePoint ASPX Page

Custom SharePoint ASPX pages are often created by modifying a Web Part page in SharePoint Designer.

Ideal Aspects

  • It uses SharePoint functionality as much as possible
  • It depends on things other than SharePoint as little as possible

Non-ideal Aspects

  • It interferes with the operation of the underlying platform
  • It relies on SharePoint for runtime behavior
  • It is a direct edit to an ASP.NET file

The way a custom ASPX page interferes with the underlying platform is by creating a custom page that is subject to safe mode parsing and be compiled. As a unique object it will diverge from non-customized pages over time.

External / Provider Hosted UI

External / Provider Hosted UI serves the user interface from a provider outside of SharePoint. The custom UI consumes SharePoint services via one or more client API’s.

Ideal Aspects

  • It doesn’t interfere with the operation of the underlying platform
  • It cedes runtime control to SharePoint as little as possible
  • The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Non-ideal Aspects

  • Typically recreates functionality that could be provide by SharePoint
  • It is completely dependent on the external host

Publishing Page and Traditional SharePoint Web Part Page

These types of pages are examples of Custom SharePoint ASPX Pages and are ideal and non-ideal in the same says for the same reasons. Publishing Pages typically rely on custom master pages and page layouts. Client API’s create traditional SharePoint web part pages by copying the ASPX from an out-of-box page into a new file.

SharePoint App-in Web Hosted UI

SharePoint App-in Web Hosted UI is hosted in a special web in a domain outside of the containing site’s domain.

Ideal Aspects

  • It depends on things other than SharePoint as little as possible

Non-ideal Aspects

  • It interferes with the operation of the underlying platform
  • Typically recreates functionality that could be provide by SharePoint
  • It relies on SharePoint for runtime behavior
  • It is a direct edit to an ASP.NET file

Pages in SharePoint App-in Webs are Custom SharePoint ASPX Pages with less access to SharePoint functionality than the other types of custom pages in this competition.

SharePoint Wiki Page

SharePoint Wiki Pages are superficially similar to traditional SharePoint Web Part pages with one important difference – they are not custom ASPX pages. A wiki page is served from a shared template that changes over time.

Ideal Aspects

  • It doesn’t interfere with the operation of the underlying platform
  • It uses SharePoint functionality as much as possible
  • It depends on things other than SharePoint as little as possible
  • The other things it depends on are provided via supported mechanisms other than directly editing SharePoint Master Pages or ASP.NET files

Non-ideal Aspects

  • It relies on SharePoint for runtime behavior

The Winner!

In general, a SharePoint Wiki Page is the best type of page to use when customizing SharePoint. You can see one of our preferred design patterns in action in the IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap sample framework. I will be covering our favorite design patterns and how they are constructed in a future post.

–Doug Ware