SharePoint-Hosted Apps are also known as client-side Apps. This article lists the components of a client side App and introduces useful SharePoint Web Parts such as the Client Web Part and the Chrome Web Part. Although client-side Apps can only execute client-side code the improved client object model (CSOM) and script libraries such as jQuery make client-side Apps very powerful.
What is a SharePoint-Hosted App?
A SharePoint-Hosted App is a custom SharePoint 2013 component, built using Web technologies, and stored completely within the SharePoint content database. SharePoint-Hosted Apps are also known as client-side Apps because they can only execute client-side code, which is code that executes in the browser, not on a SharePoint server. This architecture ensures that client-side Apps do not threaten the stability of SharePoint servers or monopolize server resources. However, because the CSOM has been greatly extended in SharePoint 2013, the client-side approach does not limit the capabilities of Apps. In fact a SharePoint 2013 client-side App is more powerful than the sandboxed server-side solutions you may be familiar with in SharePoint 2010.
Parent Sites and App Sites
When a user or administrator installs a client-side App in a SharePoint site, SharePoint automatically creates a sub-site in which it installs all the pages, code, and markup that make up the App. This sub-site can include SharePoint lists, libraries, content types, items, and other objects that you define using CAML in the App's code. This approach to declarative objects has not changed for SharePoint 2013. It is easy to write CSOM JavaScript code to access all the items, lists, and libraries in the App Site. This architecture ensures that client-side apps are self-contained. When you remove a client-side app, the sub-site is removed and nothing remains in the parent site. This clean removal process is a significant advantage of apps for SharePoint.
Types of Client-Side App
Client-side Apps are of three kinds, depending on the location in the SharePoint user interface where you will find them:
- Full Page Apps. These Apps are displayed in their own web page and linked to from the parent site. The page layout and look-and-feel in the App site may be completely different from the parent site.
- Web Part Apps. These Apps are displayed in a Web Part that makes up only a portion of a page in the parent site. The majority of the parent site's user interface remains visible. For example, the Quick Launch, the navigation controls, and any branding are shared between parent site and App site.
- Command Extension Apps. These Apps add new shortcuts to SharePoint menus. For example, you could create a client-hosted App that adds a new link to the document context menu in a document library.
Building SharePoint-Hosted Apps
SharePoint-Hosted Apps differ from solutions for earlier versions of SharePoint in that their code runs entirely in the user's browser on the client-side. This has two advantages:
- A badly-written App cannot threaten SharePoint 2013 server stability because the code does not run on the server. If an app stops responding in a user's browser, other users connected to the same SharePoint server are not affected.
- An App that uses processing or memory intensively does not monopolize resources on the server.
User Interface
Client-side Apps display their user interface in the browser so you must design and style that user interface by using HTML and CSS just as you would design and style a stand-alone Web page. Create elements that users can click on or type text into or interact with in other ways. You will use a script to respond to these events.
Scripting Language and Libraries
Code that responds to user input and executes logic in a client-side app is written in JavaScript and runs in the browser. JavaScript is not compiled to machine or managed code but instead is interpreted, at run time, by the JavaScript engine in the browser. Most Web browsers support JavaScript although there are differences in their implementations. Several script libraries make it much easier to write JavaScript code that accesses SharePoint 2013. Some of these are exclusively used with SharePoint, others are general libraries intended for scripting on any Web page but useful in Apps:
- CSOM: SharePoint 2013 includes an extended CSOM that you will use throughout your apps for SharePoint. Almost all SharePoint functionality is available through this script library.
- AJAX: This JavaScript library is used in ASP.NET application to run client-side code and increase responsiveness. It makes it simple to call SharePoint2013 asynchronously, for example to load data from a list or library.
- jQuery: This library is very popular for all JavaScript applications and complements AJAX. It includes functions that you can call to work around differences between browsers. In this way, you can rapidly write code that is independent of the browser the user runs.
Structure of a Client-Side App Project
Visual Studio 11 includes a project template for creating apps for SharePoint. The following shows a new project created from that template in Project Explorer and illustrates its structure. It includes the following elements:
- Pages: This folder contains the HTML files that define your App's user interface.
- Scripts: This folder contains the JavaScript files that respond to user input and implement business logic.
- Styles: This folder contains the CSS files that style your App's user interface.
- Features: Features are used to deploy declarative objects in your App, such as list definitions, list instances, and content types. This mechanism has not changed from SharePoint 2010.
- Package: All the Features in your project are compiled into a single package file. Again this has not changed. The package file is included in the apps for SharePoint file when you publish it.
- AppManifest.xml: This crucial file identifies the App as apps for SharePoint and defines the permissions the App requires to run.
- As you build the App from this starting point, you add HTML pages, script file, styles, and so on.
Using Built-In Controls
There are two user interface controls frequently used in SharePoint-Hosted Apps. These controls make it easy to integrate your App with the SharePoint user interface and present a consistent look and feel.
The Client Web Part
SharePoint 2013 includes many Web Parts and you can add your own because the SharePoint solutions you are familiar with from SharePoint 2010 are still supported. Web Parts are helpful because they enable users to modify SharePoint pages to their own requirements without writing any code. Web Parts can be moved around a page and connected by users to build dashboards that present data. Apps for SharePoint are not Web Parts however, by using the Client Web Part that comes with SharePoint 2013, you can present them as a Web Part that users can add to pages wherever they need them. The Client Web Part therefore distinguishes Web Part Apps from Full Page Apps and Command Extension Apps. This Web Page enables apps to behave precisely as Web Parts do in the SharePoint user interface.
The Chrome Control
SharePoint 2013 comes with a default look and feel that consists of colors, fonts, styles, and menus in various locations on the page. Site templates and themes can alter this look and feel. In addition, power users and developers may have created custom master pages that impart completely new styles on their sites. In fact a SharePoint page may not look like the default scheme at all. This presents a problem to developers who want an App to blend seamlessly into any site. If, for example, you hardcode your style to look like the default SharePoint style it will work well when no design changes have been made. However, in the many sites where branding is in place and styles have been altered your App will stick out and present an unpleasant contrast in presentation. You can use the Chrome Control to overcome this problem. The Chrome Control downloads a copy of the style sheet used in the parent site and applies it to the HTML pages in your client-side App. You can use this control to automatically inherit styles from the parent site and can blend with any site where users install your app. The Chrome Control also helps the developers by making it easy to create menus within apps for SharePoint. This is a very rapid way to build navigation into your custom App.
Cross-Domain Calls
In Web site development, cross-domain scripting is a technique used by attackers to inject their own scripts into other site's Web pages. By using this technique a hacker can compromise security, gain access to other users' details, or create a denial-of-service attack. Therefore most Web servers and applications will not run any script that does not originate from a local site. They consider any script from another site to be untrustworthy. However, when you build apps for SharePoint, whether it is a client-side, server-side, or hybrid App, you frequently need access to data in other sites. For example, as you have seen, a client-side App exists in a separate sub-site within the parent site where it was installed. A client-side app frequently needs to display data from lists in the parent site. Ordinarily this would be considered a cross-domain call and the parent Web would deny access. SharePoint 2013 provides a secure way to register and enable cross-domain calls for a limited set of well-known sites, so that Apps, parent sites, and other sites can trust each other and access each other's data.
Coding Cross-Domain Calls
SharePoint 2013 includes the following components that you must use to enable secure cross-domain calls:
- The SP.RequestExecutor.jsJavaScript Library. This library is located in the LAYOUTS directory within the SharePoint 2013 hive and therefore is well-known and trusted by all SharePoint sites in your farm. It includes all the JavaScript functions you need to access data outside your current App site.
- The AppWebProxy.aspx Page. This ASP.NET page is also located in the LAYOUTS directory and so it is widely trusted. In the calling site, you load this page in a hidden IFrame, then use SP.RequestExecutor.js to communicate with it.
- Domain Registration. An App that implements the previous components cannot make cross-domain calls unless the user or administrator who installs it and grants permission. This is called Domain Registration.
The App requests the AppWebProxy.aspx page from the parent Web and loads it into a hidden IFrame in its user interface. The App also includes the SP.RequestExecutor.js library. In your custom App scripts, you can call functions in that library. These functions communicate with the AppWebProxt.aspx in the Parent Web. This page can access list items in the parent Web and return them, through the SP.RequestExecutor.js library to your script.