Sharepoint 2013 : Understanding SharePoint app model architecture (part 6) - Working with app user-interface entry points - Building app part

An app part is a user interface element that is surfaced on pages in the host web by using an IFrame. Once an app with an app part has been installed, a user can then add an app part to pages in the host web by using the same user interface experience that is used to add standard web parts.

You implement an app part in Visual Studio 2012 by using a client web part. This makes most developers ask, “What’s the different between an app part and a client web part?” The best way to think about this is that the term “app part” is meant for SharePoint users, whereas the term “client web part” is used by developers to describe the implementation of an app part.

Despite having similar names, client web parts are very different from the standard web parts that are familiar to most SharePoint developers. In particular, a client web part cannot have any server-side code that runs within the SharePoint host environment. The implementation of a client web part must follow the rules of SharePoint app development.

Client web parts are supported under each of the three app hosting models. You implement a client web part in a SharePoint-hosted app by using HTML, CSS, and JavaScript. In a cloud-hosted app, you also have the option of implementing the behavior for a client web part by using server-side code in the remote web.

At first, many developers assume that a client web part is nothing more than an IFrame wrapper around an external web page. However, the client web part provides significant value beyond that. When you configure the URL within a client web part, you can use the same tokens as with the start page, such as ~appWebUrl, ~remoteAppUrl, and {StandardTokens}. Client web parts also support adding custom properties, as well. Furthermore, the page behind a client web part is often passed contextual security information that allows it to call back into the SharePoint host environment with an established app identity. You can think of the client web part as an IFrame on steroids.

When you want to add a new client web part to a SharePoint app project, you use the Add New Item command. The Add New Item dialog box in Visual Studio 2012 provides a Client Web Part item template, as shown in Figure 7.

When you add a new project item for a client web part, Visual Studio 2012 adds an elements.xml file to the SharePoint app project that contains a ClientWebPart element. The following code is a simple example of the XML definition for a client web part in a SharePoint-hosted app project that is implemented by using a page inside the app web:

Figure 7. The Add New Item dialog provides templates for adding client web parts and UI custom actions to app projects.

<ClientWebPart Name="MyAppPart" Title="My App Part" Description="My description"
               DefaultWidth="300" DefaultHeight="200" >

  <Content Type="html" Src="~appWebUrl/Pages/AppPart1.aspx" />

</ClientWebPart>

As you can see from this example, the content displayed in a client web part is configured by assigning a URL to the Src attribute of the <Content> element. The web page that is referenced by this URL is usually added to either the app web or to the remote web. However, you can even reference a web page on the Internet that is neither in an app web nor in a remote web. The only important restriction is that the web page cannot be returned with the X-Frame-Options header in the HTTP response. This is a header used by some websites to prevent its pages from being used inside an IFrame with a type of attack known as clickjacking.

Here is something that can catch you off guard when creating a client web part in a SharePoint-hosted app: the default behavior of SharePoint 2013 is to add the X-Frame-Options header with a value of SAMEORIGIN in the HTTP response when it serves up pages from a SharePoint site. The result of this is that a page served up from the app web will not work when you attempt to use it as the page behind a client web part. The way to deal with this problem is to add the following directive to the top of any page in the app web referenced by a client web part to suppress the default behavior of adding the X-Frame-Options header:

<WebPartPages:AllowFraming ID="AllowFraming" runat="server" />

When you develop client web parts, you can add custom properties. The real value of custom properties is that they can be tailored by the user in the browser in the same fashion as a user customizes the properties of standard web parts. You define a custom property by adding a <Properties> element into the <ClientWebPart> element and then adding a <Property> element within that, as illustrated in Example 2.

<Properties>
  <Property
    Name="MyProperty"
    Type="string"
    WebBrowsable="true"
    WebDisplayName="My Custom Property"
    WebDescription="Insightful property description"
    WebCategory="Custom Properties"
    DefaultValue="Some default value"
    RequiresDesignerPermission="true" />
</Properties>

Once you have added a custom property, you must then modify the query string at the end of the URL that is assigned to the Src attribute in the <Content> element. You do this by adding a query string parameter and assigning a value based on a pattern by which the property name is given an underscore before it and after it. Thus, for a property named MyProperty, you should create a query string parameter and assign it a value of _MyProperty_. This would result in XML within the <Content> element that looks like the following:

<Content
  Type="html"
  Src="~appWebUrl/Pages/AppPart1.aspx?MyPropertyParameter=_MyProperty_"
/>

Note that you can use any name you want for the query string parameter itself. It’s when you assign a value to the parameter that you have to use actual property name and follow the pattern of adding the underscores both before and after.