2 out of 6 rated this helpful - Rate this topic

How to: Create app parts to deploy with apps for SharePoint

apps for Office

Published: July 16, 2012

How to

Learn how to create an app part in SharePoint 2013 that is available in the Web Part gallery of the host web when you deploy your app for SharePoint.

Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

In this article
Prerequisites for using the examples in this article
Code example: Create an app part to deploy to the host web’s Web Part gallery
Next steps
Additional resources

Watch the video: Design patterns for apps for SharePoint 2013

Code samples
Display remote app content in the host web using an app part

With app parts, you can show your app user experience (UX) right in the host web. An app part displays your app content using an IFrame. End users can customize the experience using the custom properties that you can provide for your app part. The app webpage receives the custom property values through parameters in the query string.

The example in this article uses an HTML page as the content page. You can also use SharePoint ASPX pages to host the app part content. For more information, see Extending SharePoint UI in apps.

Prerequisites for using the examples in this article

To follow the steps in this example, you will need the following:

Microsoft Visual Studio 2012
SharePoint development tools in Visual Studio 2012
A SharePoint 2013 development environment (app isolation required for on-premises scenarios)

For guidance on how to set up a development environment that fits your needs, see Start building apps for Office and SharePoint.

Core concepts to help you understand app parts

The following table lists useful articles that can help you understand the concepts that are involved in an app part scenario.

Table 1. Core concepts for app parts

Article title	Description
Apps for SharePoint overview	Learn about the new app model in Microsoft SharePoint 2013 that enables you to create apps, which are small, easy-to-use solutions for end users.
UX design for apps in SharePoint 2013	Learn about the UX options that you have when you are building apps for SharePoint.
Host webs, app webs, and SharePoint components in SharePoint 2013	Learn about the difference between host webs and app webs. Find out which SharePoint 2013 components can be included in an app for SharePoint, which components are deployed to the host web, which components are deployed to the app web, and how the app web is deployed in an isolated domain.

Code example: Create an app part to deploy to the host web’s Web Part gallery

To deploy an app part to the host web’s Web Part gallery, follow these steps:

Create the app for SharePoint and remote web projects.
Add the app part feature to the app for SharePoint project.
Add an app webpage for the app part.

Figure 1 shows a Web Parts page hosting the Basic app part.

Figure 1. Web Parts page hosting the Basic app part.

Web part page hosting the basic app part

To create the app for SharePoint and remote web projects

Open Visual Studio 2012 as administrator. (To do this, right-click the Visual Studio 2012 icon on the Start menu, and choose Run as administrator.)
Create a new project using the App for SharePoint 2013 template
Figure 2 shows the location of the App for SharePoint 2013 template in Visual Studio 2012, under Templates, Visual C#, Office SharePoint, Apps.
Figure 2. App for SharePoint 2013 Visual Studio template
Provide the SharePoint website’s URL that you want to use for debugging.
Select Autohosted or Provider-hosted as the hosting option for your app.
After the wizard finishes, you should have a structure in Solution Explorer that resembles Figure 3.
Figure 3. App for SharePoint projects in Solution Explorer

To add an app webpage for the app part

Right-click the web project, and add a new Web Form. Rename the Web Form AppPartContent.

Copy the following markup and paste it in the HTML page. The markup performs the following tasks:

Provides placeholders for the custom property values.
Extracts the property values from the query string.
Renders an edit mode message if the editmode property value equals 1.
Renders the property values in the placeholders if the editmode property value equals 0.

JavaScript

<!DOCTYPE HTML>
<html>
    <body>
        <!-- Placeholder for edit mode message -->
        <h1 id="editmodehdr" style="display:none">
            The app part is in edit mode.
        </h1>

        <div id="content">
            <!-- Placeholders for properties -->
            String property: <span id="strProp"></span><br />
            Integer property: <span id="intProp"></span><br />
            Boolean property: <span id="boolProp"></span><br />
            Enumeration property: <span id="enumProp"></span><br />
        </div>

    <!-- Main JavaScript function, controls the rendering
         logic based on the custom property values -->
    <script lang="javascript">
        "use strict";

        var params = document.URL.split("?")[1].split("&");
        var strProp;
        var intProp;
        var boolProp;
        var enumProp;
        var editmode;

        // Extracts the property values from the query string.
        for (var i = 0; i < params.length; i = i + 1) {
            var param = params[i].split("=");
            if (param[0] == "strProp")
                strProp = decodeURIComponent(param[1]);
            else if (param[0] == "intProp")
                intProp = parseInt(param[1]);
            else if (param[0] == "boolProp")
                boolProp = (param[1] == "true");
            else if (param[0] == "enumProp")
                enumProp = decodeURIComponent(param[1]);
            else if (param[0] == "editmode")
                editmode = decodeURIComponent(param[1]);
        }

        // If the app part is in edit mode.
        if (editmode == 1) {
            // Display an edit mode banner.
            document.getElementById("editmodehdr").style.display = "inline";
            document.getElementById("content").style.display = "none";
        }
        else {
            // Uses the placeholders to render the property values.
            document.getElementById("strProp").innerText = strProp;
            document.getElementById("intProp").innerText = intProp;
            document.getElementById("boolProp").innerText = boolProp;
            document.getElementById("enumProp").innerText = enumProp;

            // Hide the edit mode banner and display the content.
            document.getElementById("editmodehdr").style.display = "none";
            document.getElementById("content").style.display = "inline";
        }
    </script>
</body>
</html>

If you are using a SharePoint page, you must use the Allowframing Web Part somewhere on your page. The following code example shows how to use the Allowframing Web Part on a SharePoint page.

HTML

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

To add the app part feature to the app for SharePoint project

Right-click the app for SharePoint project, and add a new Client Web Part item.
In the Specify the client Web Part page dialog box, choose Select or enter a URL for an existing web page. Choose the AppPartContent page in the drop-down menu.

Set the following custom properties for the app part.

Table 2. App part custom properties

DefaultValue	Name	Type	WebCategory	WebDisplayName
String default value	strProp	string	Basic app part category	A property of type string
0	intProp	int	Basic app part category	A property of type integer
false	boolProp	boolean	Basic app part category	A property of type boolean
1st	enumProp	enum	Basic app part category	A property of type string

Add the following enum items to the enumProp property.
Table 3. Enum items of the enumProp property
Value
WebDisplayName
1st
First option
2nd
Second option
3rd
Third option

Value	WebDisplayName
1st	First option
2nd	Second option
3rd	Third option

Visual Studio generates the following markup in the elements.xml file of the app part feature.

XML

<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ClientWebPart
        Title="Basic app part"
        Name="Basic app part"
        Description="This is a basic app part with custom properties." >
        
        <!--  The properties are passed through the query string 
                using the following notation: _propertyName_
                in the Src property of the Content element.  
          -->
        <Content
            Src="~remoteAppUrl/AppPartContent.html?strProp=_strProp_&amp;intProp=_intProp_&amp;boolProp=_boolProp_&amp;enumProp=_enumProp_"
            Type="html"/>
        <Properties>
            <Property
                Name="strProp"
                Type="string"
                RequiresDesignerPermission="true"
                DefaultValue="String default value"
                WebCategory="Basic app part category"
                WebDisplayName="A property of type string.">
            </Property>
            <Property
                Name="intProp"
                Type="int"
                RequiresDesignerPermission="true"
                DefaultValue="0"
                WebCategory="Basic app part category"
                WebDisplayName="A property of type integer.">
            </Property>
            <Property
                Name="boolProp"
                Type="boolean"
                RequiresDesignerPermission="true"
                DefaultValue="false"
                WebCategory="Basic app part category"
                WebDisplayName="A property of type boolean.">
            </Property>
            <Property
                Name="enumProp"
                Type="enum"
                RequiresDesignerPermission="true"
                DefaultValue="1st"
                WebCategory="Basic app part category"
                WebDisplayName="A property of type enum.">
                <EnumItems>
                    <EnumItem WebDisplayName="First option" Value="1st"/>
                    <EnumItem WebDisplayName="Second option" Value="2nd"/>
                    <EnumItem WebDisplayName="Third option" Value="3rd"/>
                </EnumItems>
            </Property>
        </Properties>
    </ClientWebPart>
</Elements>

Append the following query string parameter to the Src attribute of the Content element in the elements.xml file.
XML
Copy
&editmode=_editMode_
The _editMode_ token allows your content page to determine if the app part is in edit mode. If the app part is in edit mode, the _editMode_ token resolves to 1; otherwise, the token resolves to 0.

To build and run the solution

Make sure that the app for SharePoint project is set as the startup project.
Press the F5 key.
Note
When you press F5, Visual Studio builds the solution, deploys the app, and opens the permissions page for the app.
Choose the Trust It button.
Go to any wiki page or Web Parts page in the host web.
Edit the page and add the Basic app part from the Web Part gallery.
Figure 5 shows the Basic app part in the host web’s Web Part gallery.
Figure 5. Basic app part in the Web Part gallery

Note
When you press F5, Visual Studio builds the solution, deploys the app, and opens the permissions page for the app.

Table 2. Troubleshooting the solution

Problem	Solution
Visual Studio does not open the browser after you press the F5 key.	Set the app for SharePoint project as the startup project.
The app part does not display any content. The app part displays the following error: Navigation to the webpage was canceled.	The browser blocked the content page. The solution might be different depending on the browser you are using: Internet Explorer 10 and 9 display the following message at the bottom of the page: Only secure content is displayed. Click Show all content to display the app part content. Internet Explorer 8 shows a dialog box with the following message: Do you want to view only the webpage content that was delivered securely?. Click No to display the app part content.

Problem

Solution

Visual Studio does not open the browser after you press the F5 key.

Set the app for SharePoint project as the startup project.

The app part does not display any content. The app part displays the following error: Navigation to the webpage was canceled.

The browser blocked the content page. The solution might be different depending on the browser you are using:

Internet Explorer 10 and 9 display the following message at the bottom of the page: Only secure content is displayed. Click Show all content to display the app part content.
Internet Explorer 8 shows a dialog box with the following message: Do you want to view only the webpage content that was delivered securely?. Click No to display the app part content.

Next steps

This article demonstrated how to create an app part in an app for SharePoint. As a next step, you can learn about the other UX components that are available for apps for SharePoint. To learn more, see the following:

Additional resources

Change history

Date	Description
July 16, 2012	Initial publication

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Additions

ADD