in

Dot Net Mafia

Group site for developer blogs dealing with (usually) .NET, SharePoint 2013, SharePoint 2010, Office 365, SharePoint Online, and other Microsoft products, as well as some discussion of general programming related concepts.

This Blog

Syndication

Archives

Corey Roth [MVP]

A SharePoint MVP bringing you the latest time saving tips for SharePoint 2013, Office 365 / SharePoint Online and Visual Studio 2013.

How to: Build a SharePoint-hosted Client Web Part in SharePoint 2013

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.

VS12RCNewSharePointApp

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.

VS12RCNewAppSettings

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:

VS12RCClientWebPartSPI

When the Client Web Part is created, you’ll get an XML file that looks like this.

ClientWebPartNewXml

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. 

VS12RCPageSPI

The default page looks like this.

ClientWebPartPageDefault

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.

ClientWebPartNoFramingError

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.

DeveloperSiteApps

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.

PageInsertAppPart

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.

PageInserWebPartApps

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.

ClientWebPartOnPage

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.

Comments

 

SharePoint Daily » Blog Archive » Build a SharePoint 2013 Web Part; Outlook.com: Fighting for the Workplace; Free Microsoft eBooks said:

Pingback from  SharePoint Daily  &raquo; Blog Archive   &raquo; Build a SharePoint 2013 Web Part; Outlook.com: Fighting for the Workplace; Free Microsoft eBooks

August 2, 2012 7:48 AM
 

SharePoint Daily said:

Microsoft is building a robotic &quot; big brother &quot; to watch over you at work. - Dooley Top News

August 2, 2012 7:57 AM
 

Hilton Giesenow said:

Hey Cory,

thanks for the intro. One typo, I think. For "If all goes well, your Client Web Part should not be visible on the page.", I think you mean "...should NOW be visible..."

August 2, 2012 3:16 PM
 

CoreyRoth said:

Thanks Hilton for the catch.  I've updated the post.

August 2, 2012 3:30 PM
 

Peso said:

The part with the AllowFraming tag is mentioned in the offical Microsoft Developer Videos ;-) The particular one I think of is from Scot Hillier. You should definitely watch them.

August 3, 2012 12:01 AM
 

The Microsoft MVP Award Program Blog said:

1. Creating OData Service Using WCF By Visual C# MVP Amit Choudhary – @vendettamit 2. Active Directory

August 10, 2012 4:05 PM
 

UpSearch said:

Pingback from  UpSearch

August 10, 2012 7:14 PM
 

UpSearch said:

Pingback from  UpSearch

August 10, 2012 7:15 PM
 

Friday Five???August 10, 2012 | MSDN Blogs said:

Pingback from  Friday Five???August 10, 2012 | MSDN Blogs

August 11, 2012 9:00 AM
 

Friday Five???August 10, 2012 | MSDN Blogs said:

Pingback from  Friday Five???August 10, 2012 | MSDN Blogs

August 11, 2012 10:00 AM
 

Hannes said:

Hi Corey,

Thanks for the information.

Referring to the folling excerpt from your post:

"You can pass properties from the the user enters from ClientWebPart itself to the page here, but we’ll cover that in another post."

Could you please direct me to the location of this post, if it exists?

I have a situation like this: SharePoint-Hosted WebPart with a custom property. The user should be able to enter a value for the property which should then be sent to the WebPart to alter appearance and behaviour. Error handling might also be necessary.

Thank you in advance for your time and effort.

Kind regards,

Hannes.

August 23, 2012 3:23 AM
 

UpSearch said:

Pingback from  UpSearch

August 26, 2012 1:25 PM
 

UpSearch said:

Pingback from  UpSearch

August 26, 2012 7:43 PM
 

UpSearch said:

Pingback from  UpSearch

August 26, 2012 11:26 PM
 

UpSearch said:

Pingback from  UpSearch

August 26, 2012 11:33 PM
 

UpSearch said:

Pingback from  UpSearch

August 27, 2012 6:32 AM
 

CoreyRoth said:

@Hannes I haven't had a chance to right it yet but I should have it in the next week or so barring any unusual circumstances.

August 29, 2012 6:38 PM
 

Sara said:

Very useful information.

One big area that I have enjoyed looking into SHarepoint 2013 is the area of Social within SharePoint. In the past, social elements such as My Sites and tagging were nice, but they didn’t really drive me to use them. Within 2013, the story changes. So much more is available and the changes are great improvements that will drive Social sites to be the central hub for a user.

- Sara

September 4, 2012 4:19 AM
 

Blog del CIIN said:

Os dejo un primer recopilatorio de recursos sobre el nuevo modelo de Aplicaciones de SharePoint 2013

October 5, 2012 6:51 AM
 

SharePoint 2013: Recursos sobre el nuevo modelo de creación de aplicaciones (I)! « Pasi??n por la tecnolog??a… said:

Pingback from  SharePoint 2013: Recursos sobre el nuevo modelo de creaci&oacute;n de aplicaciones (I)! &laquo; Pasi??n por la tecnolog??a&#8230;

October 5, 2012 6:55 AM
 

Getting started with building apps for SharePoint 2013 « Software Architecture Blog said:

Pingback from  Getting started with building apps for SharePoint 2013 &laquo; Software Architecture Blog

November 19, 2012 3:18 PM
 

Vijay Arul Lourdu said:

Hi,

Thanks for the great post.I am trying to achieve the same with the custom app part properties also.

for example working fine in IFRAME

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

i am exactly getting the Provider Hosted app web in IFRAME.

But when i am trying to do the same with custom app part properties.

Src="~remoteAppUrl/Coffeemaker.html?name=_name_&amp;teaspoons=_teaspoons_&amp;decaf=_decaf_&amp;size=_size_&amp;{StandardTokens}"

I have a html file for reading the properties and i am navigating to the Provider host web in Appmanifest.xml file.

when i have properties its opening in different window than IFRAME.

Is it possible to open the Provider hosted app web in IFRAME along with custom app part properties.

i have used the cofee maker app part sample in

code.msdn.microsoft.com/SharePoint-2013-App-part-9d83703c

December 4, 2012 7:04 AM
 

Matt Ranlett said:

The HTML version specified in the MSDN examples require in newer builds the inclusion of the 405 fix - a handler for static files.  Works great on the app part but no other pages for that app will work - they get rendered as flat HTML

December 21, 2012 1:38 AM
 

Nick Johnson said:

Thanx for explaining a complex structure in a very simple way. Screen-shots attached became very helpful in understanding the whole process.....

March 1, 2013 4:10 AM
 

sandronikos said:

I followed all the steps & I get an error like:

Warning 1 File '~masterurl/default.master' was not found. What am i doing wrong ?

March 1, 2013 8:49 AM
 

CoreyRoth said:

@Nick Thanks!

@sandronikos I haven't seen it before.

April 11, 2013 10:18 PM
 

Use the SharePoint 2013 Client Object Model (SP.js) from a Client Web Part said:

Pingback from  Use the SharePoint 2013 Client Object Model (SP.js) from a Client Web Part

July 10, 2013 10:29 PM

Leave a Comment

(required)  
(optional)
(required)  
Add

About CoreyRoth

Corey Roth is an Applications Architect at Infusion specializing in ECM and Search.
2012 dotnetmafia.
Powered by Community Server (Non-Commercial Edition), by Telligent Systems