Lab.md

Deep Dive into SharePoint Hosted Apps

In this lab, you will

Prerequisites

1. You must have an Office 365 tenant to complete this lab. If you do not have one, the lab for O3651-7 Setting up your Developer environment in Office 365 shows you how to obtain a trial.

Exercise 1: Create a SharePoint-Hosted App

In this exercise you will create a basic SharePoint-Hosted app that you can enhance in follow-on exercises.

1. Create the new project in Visual Studio 2013:
2. Launch Visual Studio 2013 as administrator.
3. In Visual Studio select File/New/Project.
4. In the New Project dialog: 1. Select Templates/Visual C#/Office/SharePoint/Apps. 2. Click App for SharePoint 2013. 3. Name the new project DeepDiveSPApp and click OK.
   
5. In the New App for SharePoint wizard: 1. Enter the address of a SharePoint site to use for testing the app (NOTE: The targeted site must be based on a Developer Site template) 2. Select SharePoint Hosted as the hosting model. 3. Click Finish.
   4. When prompted, log in using your O365 administrator credentials.
6. Test the app
7. After the project is created, press F5 to debug the app.
8. Verify that the app launches and greets you.
   
9. Stop debugging.
10. The code in the project template utilizes the client-side object model (CSOM). However, it can be rewritten to utilize the equivalent REST calls.
11. Open the app.js file located in the scripts folder.
12. Delete all of the JavaScript code in the file.
13. Add the following code to the app.js file.

(function () {
    "use strict";

    jQuery(function () {

        jQuery.ajax({
            url: "../_api/web/currentuser",
            type: "GET",
            headers: {
                "accept": "application/json;odata=verbose",
            },
            success: function (data, status, jqXHR) {
                jQuery("#message").text("Welcome, " + data.d.Title);
            },
            error: function (jqXHR, status, message) {
                jQuery("#message").text(message);
            }
        });

    });

}());

4. Press F5 to debug the app.
5. Verify that the app launches and greets you.

Exercise 2: Create an App Part

In this exercise you will add an app part to your project for displaying song titles based on a specified artist.

1. Add the new Client Web Part
2. In Visual Studio 2013, right click the DeepDiveSPApp project and select Add/New Item.
3. In the New Item dialog, select Client Web Part (Host Web).
4. Name the new app part MusicPart and click Add.
   
5. In the Specify the Client Web Part Page dialog, select Create a New App Web Page for the Client Web Part Content.
6. Click Finish
   
7. In the Element.xml file that describes the Client web part, replace the ClientWebPart element with the following code.

<ClientWebPart 
  Name="MusicPart" 
  Title="Music App Part" 
  Description="Displays songs from a specified artist" 
  DefaultWidth="300" 
  DefaultHeight="200">

  <Content Type="html" Src="~appWebUrl/Pages/MusicPart.aspx?{StandardTokens}&amp;Artist=_Artist_" />

  <Properties>
    <Property
      Name="Artist"
      Type="string"
      WebBrowsable="true"
      WebDisplayName="Artist"
      WebDescription ="The artist to search"
      WebCategory="Configuration"
      DefaultValue="artist"
      RequiresDesignerPermission="true"
      PersonalizableIsSensitive="false"
      PersonalizationScope="shared"/>
  </Properties>

</ClientWebPart>

2. Prepare the App Part user interface
3. Open MusicPart.aspx for editing.
4. Add the following HTML to the body element for displaying information in the app part.

  <div>
      <ul id="songList"></ul>
  </div>

3. Add the following script reference to the head section to include functionality for the app part.

<script type="text/javascript" src="../Scripts/apppart.js"></script>

3. Code the App Part.
4. Right click the scripts nodeand select Add/New Item.
5. In the Add New Item dialog, select Web and then JavaScript File.
6. Name the new file apppart.js.
7. Click Add.
   
8. Add* the following code to apppart.js to call the MusicBrainz service and display songs for the designated artist.

(function () {
    "use strict";

    $(function () {

        var ctx = SP.ClientContext.get_current();
        var request = new SP.WebRequestInfo();

        request.set_url(
            "http://www.musicbrainz.org/ws/2/release-group?query=artist:" + artist
            );
        request.set_method("GET");
        responseDocument = SP.WebProxy.invoke(ctx, request);
        ctx.executeQueryAsync(onSuccess, onError);

    });

}());

var onSuccess = function () {
    var xmlDoc = $.parseXML(responseDocument.get_body());
    $(xmlDoc).find("release-group").each(function (i) {
        var title = $(this).children("title").first().text();
        $("#songList").append("<li>" + title + "</li>")
    });
}

var onError = function () {
    alert("failed!");
}

var getQueryStringParameter = function (p) {
    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] == p)
            return decodeURIComponent(singleParam[1]);
    }
}

var artist = getQueryStringParameter("Artist");
var responseDocument = "";

4. Test the App Part
5. Open AppManifest.xml
6. Click Remote Endpoints
7. Add the endpoint http://www.musicbrainz.org and click Add
   
8. Press F5 to start debugging.
9. When the app launches, navigate away from the app home page to the home page of the host web.
10. Place the page in edit mode.
11. Click Insert/App Part.
12. Select the Music App Part and click Add
    
13. Hover over the app part and select Edit Web Part from the menu.
14. In the Web Part Properties, change the Artist property to a different value.
15. Click OK and verify that songs appear in the app part.
16. Stop debugging.

Exercise 3: Create a Menu Item custom action

In this exercise you will add a Menu Item custom action to invoke the song search from a SharePoint list.

1. Add the new Menu Item Custom action
2. In Visual Studio 2013, right click the DeepDiveSPApp project and select Add/New Item.
3. In the New Item dialog, select Menu Item Custom Action.
4. Name the new app part SongSearchAction and click Add.
   
5. In the Specify the Properties to Create Custom Action for menu Item dialog 1. Select Host Web 2. Select List Template 3. Select Custom List
   4. Click Next
   
6. In the Specify the Properties to Create Custom Action for menu Item dialog 1. Enter Song Search as the title 2. Enter DeepDiveSPApp\Pages\MusicPart.aspx as the target page 3. Click Finish
   
7. Open MusicPart.aspx for editing.
8. Add the following script reference to the head section just before the apppart.js reference.

  <script type="text/javascript" src="/_layouts/15/sp.requestexecutor.js"></script>

2. Code the Menu Item Custom Action
3. Open apppart.js for editing.
4. Add the following code to the bottom on the file to retrieve an artist name from a custom list selection.

var appWebUrl = getQueryStringParameter("SPAppWebUrl");
var hostWebUrl = getQueryStringParameter("SPHostUrl");
var listId = getQueryStringParameter("SPListId");
var listItemId = getQueryStringParameter("SPListItemId");

if (typeof (listId) != "undefined" && typeof (listItemId) != "undefined") {
    listId = listId.substring(1, listId.length - 1);
    var executor = new SP.RequestExecutor(appWebUrl);
    executor.executeAsync({
        url: "../_api/SP.AppContextSite(@target)/web/lists(guid'" + listId +
             "')/getItemByStringId('" + listItemId +
             "')?@target='" + hostWebUrl + "'",
        method: "GET",
        headers: {
            "accept": "application/json;odata=verbose",
        },
        success: function (data) {
            artist = JSON.parse(data.body).d.Title;
        },
        error: function (data) {
            artist = "artist";
        }
    });
}

3. Enclose the call to MusicBranz in a timeout function as a simple way to ensure the artist name is retrieved from the list before the call is made. The following code shows how this is done

      setTimeout(function () {

          var ctx = SP.ClientContext.get_current();
          var request = new SP.WebRequestInfo();

          request.set_url(
              "http://www.musicbrainz.org/ws/2/release-group?query=artist:" + artist
              );
          request.set_method("GET");
          responseDocument = SP.WebProxy.invoke(ctx, request);
          ctx.executeQueryAsync(onSuccess, onError);

      }, 2000)

3. Test the Menu Item custom action
4. Open AppManifest.xml
5. Click Permissions
6. Select Web for the Scope.
7. Select Read for the Right
   
8. Press F5 to start debugging.
9. When the app launches, navigate away from the app home page to the home page of the host web.
10. On the host web home page, click Site Contents.
11. Click Add an App.
12. Click Custom List.
13. Name the new list Artists.
14. Click Create
    
15. Add a new artist name to the list.
16. Using the item menu, select Song Search.

Congratulations! You have completed investigating SharePoint-Hosted apps.