How to: Build a SharePoint-hosted Client Web Part in SharePoint 2013
Posted
Wednesday, August 1, 2012 8:33 PM
by
CoreyRoth
NOTE: This post is build with Visual Studio 2012 RC and Preview 1 of the Office Developer Tools. See this post for an update with Preview 2 of the Office Developer Tools and the RTM version of SharePoint 2013.
I am extremely interested in the new SharePoint 2013 App model so I have been doing a lot with them lately. The latest thing I was trying was building a SharePoint-hosted Client Web Part. I have found that there is not a lot of information out there yet on how to use these so I wanted to share some of the things I ran into. This post on MSDN is good to help you get started with the setup of your app. Hopefully this info will help you get started. This post assumes you have installed Visual Studio 2012 RC as well as the SharePoint development tools.
After you open Visual Studio 2012 RC, create a new SharePoint app by choosing Office / SharePoint –> Apps –> App for SharePoint 2013.
You’ll then be prompted for the type of app as well as a name and deployment location. For the deployment location, you need to specify the URL to a site created with the Development Site template. I created a new site collection for this. I am not sure if it is required or not but I am fairly certain it is.
At this point, you’ll have a new SharePoint-hosted App project. Now, we just need to add the pieces that we need. However, first you need to understand a little bit about the ClientWebPart. This new type of web part is essentially two pieces: an elements.xml file and an .aspx page. The elements.xml file performs many of the same functions as a .webpart file, but it has different parameters. It’s main purpose is to specify the path to a .aspx page which it then loads in an IFRAME. Since it is an IFRAME, this page can actually be hosted anywhere: locally, on a remote web server, or in Azure. However, hosting it locally inside SharePoint is by far the simplest.
We’ll create the Client Web Part using the New Item menu:
When the Client Web Part is created, you’ll get an XML file that looks like this.
You can update the Client Web Part title, description, and size here. Note, that end users can’t change the size of the Client Web part once it’s deployed so set the value correctly here. Note the Content element. We need to update this value to the location of the associated page we are about to create. We need to specify the URL to the page associated with our ClientWebPart. To do this we make use of the ~appWebUrl token and then just specify the relative path Pages/HelloWorldClientWebPart.aspx. Here is what the entire XML looks like.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ClientWebPart Name="HelloWorldClientWebPart" Title="HelloWorldClientWebPart" Description="This is my awesome HelloWorldClientWebPart." DefaultWidth="300" DefaultHeight="200">
<!-- Content element identifies the location of the page that will render inside the client web part
Properties are referenced on the query string using the pattern _propertyName_
Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->
<Content Type="html" Src="~appWebUrl/Pages/HelloWorldClientWebPart.aspx" />
<!-- Define properties in the Properties element
Remember to put Property Name on the Src attribute of the Content element above
<Properties>
<Property Name="property1" Type="string" WebBrowsable="true" WebDisplayName="First Property" WebDescription="Description 1" WebCategory="Custom Properties" DefaultValue="String Property" RequiresDesignerPermission="true" />
</Properties> -->
</ClientWebPart>
</Elements>
You can pass properties from the the user enters from ClientWebPart itself to the page here, but we’ll cover that in another post.
Now, we need to create the page that will be loaded in the IFRAME by the Client Web Part. For simplicity, I go with the same name as the Client Web part.
The default page looks like this.
It’s this part where I couldn’t find any details on how to proceed. You might be wondering if you need to do something to this page before it will work in a Client Web Part. The answer is “yes”. If you do try to deploy it as is, you’ll get the following error when trying to use the Client Web Part.
This content cannot be displayed in a frame.
Luckily, Saurabh Bhatia came through for me in the forums and helped me out. You need to include the AllowFraming tag in your page to allow it to render in an IFRAME. Everything else in the page needs to go with the exception of the reference to the WebPartPages tag. If you leave references to the master page or content place holders, you’ll receive a heap of JavaScript errors. Here’s what my complete page looks like.
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />
<div>Hello World Client Web Part!</div>
At this point, we are ready to deploy. You can do so by pressing F5 or choosing Build –> Deploy. This will package your app and after a moment, you’ll see your app listed.
This is a Client Web Part so you don’t need to click on your App here. Instead, go to the Home Page and then edit it. Pick a place on the page and then click on Insert in the ribbon. You’ll notice this looks a bit different, choose App Part and you’ll see your new Client Web Part listed.
You might be wondering what the difference between this and Web Parts are. Not much really. If you click Web Part and then choose Apps and you’ll see the same list.
If all goes well, your Client Web Part should now be visible on the page. You may be prompted for authentication again when it loads. You can adjust your browser security settings to avoid this.
At this point, you have a working Client Web Part. You can then make use of the Client Object Model or the new REST API to interact with SharePoint. I hope this helps you get started with building some apps. Try it out and see what you can do.
UPDATE: To use the JavaScript Client Object Model with an App Part, see this post.