2. APPLICATION INTEGRATION OPTIONS IN SHAREPOINT 2013
The new application model in SharePoint
2013 offers a number of options for your application to deeply
integrate with SharePoint, other systems, and data. These options fall
into the following categories:
- User interface integration
- Events and logic integration
- Data integration
When you think about building a solution, you
must evaluate your options for how you want to surface your application
inside SharePoint (UI), how you want to call code and process actions
when a user uses your application (events and logic), and how and where
you store and work with your application’s data and data that resides
in other systems (data). Understanding what options are available and
how they work is critical when designing your application.
The following sections cover some of the most
common options you have for each of the layers (UI, events, and data)
in the new SharePoint application model.
2.1 User Interface Integration
Three main integration points are available to you in the SharePoint user interface as part of the SharePoint application model:
- App Parts and Pages
- Ribbon and Action menus
- Navigation
App Parts and Pages offer you the ability to
surface your applications’ user interface to your users. For people
familiar with SharePoint 2010, App Parts are similar to Web Parts.
Navigation lets users find your application, and integrating with the
Ribbon and Action menus lets your users take actions in the same
familiar location that they do elsewhere in SharePoint. Using one or
more of these building blocks enables you to integrate your
application’s user interface with that of SharePoint’s and expose your
app to its users.
2.1.1 App Parts and Pages
App Parts are reusable and configurable
windows into your application. They are analogous to Web Parts in
SharePoint 2010; however, the UI is generated and served remotely
within your application as opposed to being generated from code running
in the SharePoint process. Typically, the interface is rendered from
another environment such as Windows Azure in the cloud or IIS on
premises. Additionally, App Parts show in the Web Part gallery
alongside all the other Web Parts in SharePoint, so they are easy to
find and add to your SharePoint pages. Your solutions can consist of
one or more App Parts, which should typically surface parts of your
application that make sense to show alongside other Web Parts, such as
a summary of data or a small set of controls. Figure 1
shows a weather App Part that has been added to the homepage of a site.
It acts much like a Web Part would except that the UI of your
application is embedded within the part via an iFrame. This means your
application UI can be served from anywhere you choose, as long as it is
accessible from the user’s browser. As you will see later in this
section, part of an App Part’s configuration is the URL that the iFrame
should be pointed at. Along with this URL you can feed additional
parameters that your App’s logic can pick up from the query string.
These can be properties set via the App Parts property panel, for
example.
NOTE
When designing your application try to think about how parts of your
application and its data might be useful in other places, and use an
App Part if appropriate.
Pages are much like an App Part except
that they are viewed in a larger, fuller window style. Unlike with an
App Part though, when someone launches your app’s page via a navigation
link or similar method, the whole browser is directed to your app’s
page thus giving your app full control over what is displayed. This
ability enables you to include and show much more of your application
to the user. Using Pages is good for when you need a lot of room to do
things such as have the user fill in a large form or show a lot of
data. Additionally, parameters can be passed along on the URL much like
with an App Part. SharePoint provides a number of controls to assist
you in branding your application so that it fits well with the look and
feel of SharePoint. This includes a top navigation bar, as shown in Figure 2.
NOTE
To maintain a consistent user experience in your solutions, App Parts
and Pages in SharePoint 2013 allow you to include a “Chrome Control”
that adds a top navigation bar and defines standard styles for your
application. This helps you make your application UI look consistent
with that of SharePoint’s.
To get a better feel for how App Parts and Pages
work, try your hand at creating an app and adding these new elements to
it. The following activity walks you through the process.
Building Your First SharePoint Application (UserInterfaceIntegration.zip)
In this exercise you create a new
SharePoint application, add an App Part to it, and deploy it to
SharePoint Online. Prior to beginning this exercise you should have
already signed up for and created your developer Office 365 SharePoint
site. You can do that via the http://msdn.microsoft.com/sharepoint website.
1. Run Visual Studio 2012 as Administrator.
2. Select File ⇒ New ⇒ Project.
3. In the New Project dialog, expand Templates ⇒ Visual C# ⇒ Office/SharePoint ⇒ Apps.
4. Select App for SharePoint 2013 and enter the Name, MyFirstSharePointApp. Click OK.
5. In the
Specify the App for SharePoint settings dialog, provide the URL to your
Office 365 developer site and click the Validate button to confirm
connectivity to the site.
6. For the question, “How do you want to host your app for SharePoint?” select Autohosted, and then click Finish.
7. Right-click the MyFirstSharePointApp project and select Add ⇒ New Item. In the Add New Item dialog select Client Web Part and name it MyAppPart. Click Add.
8. Open the Elements.xml under MyAppPart if it is not already open.
9. Replace the
<Content Type="html" Src="" /> block with the following and save the file:
<Content Type="html" Src="~remoteAppUrl/Pages/Default.aspx?{StandardTokens}" />
10. Open the Default.aspx page.
11. Replace everything after the line starting with
<%@ Page with the following code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0
Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html >
<head runat="server">
<title></title>
<script src="https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"
type="text/javascript"></script>
<script type="text/javascript"
src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js"></script>
<script type="text/javascript">
var hostweburl;
$(document).ready(function () {
hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
var scriptbase = hostweburl + "/_layouts/15/";
var dclink = document.createElement("link");
dclink.setAttribute("rel", "stylesheet");
dclink.setAttribute("href", scriptbase + "defaultcss.ashx");
var head = document.getElementsByTagName("head");
head[0].appendChild(dclink);
});
function getQueryStringParameter(paramToRetrieve) {
var params = document.URL.split("?")[1].split("&");
var strParams = "";
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split("=");
if (singleParam[0] == paramToRetrieve)
return singleParam[1];
}
}
</script>
</head>
<body>
<form id="form1" runat="server">
<h1 class="ms-core-pageTitle">Your First SharePoint Application!</h1>
<h1 class="ms-accentText">Put your app UI here.</h1>
<div>
<h2 class="ms-webpart-titleText">Use the SharePoint CSS</h2>
<a class="ms-commandLink" href="#">links</a>
<br />
You can use the SharePoint CSS in your app by referencing it in your pages.
</div>
</form>
</body>
</html>
12. Press F5
to compile, package, deploy, and debug your application. When the
process is complete, a browser launches to a page asking, “Do you trust
MyFirstSharePointApp?” Click Trust It to continue. You should see your application listed, as shown in Figure 3:
13. Click on your app’s tile image to navigate to it. You might see a security certificate warning as shown in Figure 4.
This is because your app isn’t correctly secured with SSL while running
in your development environment. Click the Show content button to
continue.
You should see your page render as shown in Figure 5. It is using the SharePoint style sheet.
14. Navigate back to your SharePoint site.
15. Navigate to your site’s homepage by clicking the Home link in the Quick Navigation on the left side of the page.
16. Click the Page ribbon and select Edit. You will now add your new App Part to your site’s homepage.
17. Click the Insert Ribbon tab and click the App Part button.
18. Select MyAppPart from the list of parts and click Add to add the part to your page.
19. Click Save in the ribbon when the operation completes.
You should now see your new App Part
displayed on the page with both the name of your site displayed and “My
application goes here!” as shown in Figure 6. Congratulations — you have just created a SharePoint application!
How It Works
In this exercise you first created a
new project using one of the new project templates in Visual Studio
2012 for SharePoint application development. These templates provide
the starting point for any new app, a project for packaging the
declarative parts of your application that don’t include compiled code
for installation into SharePoint, and a Web project for your app’s code
for Provider-hosted and auto-hosted applications. When you run the
solution, Visual Studio packages up these projects and deploys the app
project package (.app file in the bin
directory) to your SharePoint site’s application gallery. Alongside
that process it runs your app’s code in a Web project on your local
development IIS instance. Ultimately, after your Autohosted application
is packaged for release that project will be packaged up for deployment
into a location in Azure where it will run instead.
The App Part you created is simply an HTML <iframe> window into your application as specified by the src property on the Content node of your App Parts elements.xml
file. However, it also adds some special tokens to the URL query string
of that page to pass it additional information about who the caller is.
This information is then used by the TokenHelper.GetClientContextWithContextToken
helper function to assist in the construction of a CSOM client context
that makes calls to SharePoint authenticated as that application and
caller. This ensures your app’s code can make only operations it has
been allowed to do.The JavaScript and markup that you added to
the Default.aspx page
dynamically added a style sheet link to the page, the source of which
was the CSS from your SharePoint site. It defines the styles it uses to
show the UI with the same fonts and styles as SharePoint.
As with traditional Web Parts, you may also configure App Parts with custom properties. You can do this in the Elements.xml file for the App Part. App Parts support the following types of custom properties:
- String: Gives a simple text box input field
- Int: Renders as an input field that only accepts integers
- Boolean: Renders as a check box field
- Enum: Renders as a drop-down field
For example, if you wanted your App Part to
accept a configuration property where the user could choose from one of
three options, you could use the following XML:
<Property Name="colorProp" Type="enum" RequiresDesignerPermission="true"
DefaultValue="R" WebCategory="My App Part Settings" WebDisplayName="Fav Color">
<EnumItems>
<EnumItem WebDisplayName="Red" Value="R"/>
<EnumItem WebDisplayName="Green" Value="G"/>
<EnumItem WebDisplayName="Blue" Value="B"/>
</EnumItems>
</Property>
This code would render as shown in Figure 7.
Additionally, you can choose to pass the value
set for these properties to your App Part via the URL by setting them
as tokens in the Src attribute on the Content node in the Elements.xml file:
<Content Type="html"
Src="~remoteAppUrl/Pages/Default.aspx?{StandardTokens}& Property1=_ colorProp _" />
