Tuesday, December 24, 2013

Using the When...Done Pattern with Promises in SharePoint 2013 Apps

copyright form: www.shillier.com

I have written a couple of posts about using promises to control the sequential execution of asynchronous calls in SharePoint 2013. If you are new to promises, go back to the previous posts for more information. This post will assume you understand the basics.
Instead of sequential operations, what about when you need to control multiple parallel asynchronous calls? In this post, I’ll discuss the when…done pattern in SharePoint 2013 apps using REST. Specifically, I’ll examine a scenario where an app loads, creates 2 lists programmatically, and waits for both lists to be created before rendering the user interface. This type of scenario is useful when your app must execute several initialization operations before it is ready for use.
Let’s start with a library for creating a new SharePoint 2013 list using REST.
"use strict";
var WingtipToys = window.WingtipToys || {}WingtipToys.Rest = WingtipToys.Rest || {}
WingtipToys.Rest.Lists = function () {
     var create = function (title, description, template){        var deferred = $.ajax({            url: _spPageContextInfo.webServerRelativeUrl +                 "/_api/web/lists",            type: "POST",            contentType: "application/json;odata=verbose",            data: JSON.stringify(                {                    '__metadata': {                        'type''SP.List'                    },                    'Title': title,                    'Description': description,                    'BaseTemplate': template,                    'AllowContentTypes'true,                    'ContentTypesEnabled'true                }),            headers: {                "accept""application/json;odata=verbose",                "X-RequestDigest": $("#__REQUESTDIGEST").val()            }        });
         return deferred.promise()
    };
     return {        create: create    };
 }();
This library uses an HTTP POST operation to create the new list. Notice that the library uses the $.ajax() method to make the call. Also notice that the call returns a jQuery deferred object already so there is no need for us to create one separately. The create() function simply returns the promise() from the deferred. The built in support for deferred in jQuery makes it super easy to build REST libraries for your apps.
In past examples, I’ve used the then() method of the returned promise to execute sequential asynchronous calls. In this case, however, I will use the jQuery when() method to execute multiple asynchronous calls in parallel and thedone() method to show the app’s UI when all async calls have completed. Here’s the code:
$(document).ready(function () {
    //Hide the app's UI    $("#mainDiv").hide();    $("#loadingDiv").show();

    //Create 2 announcement lists with 2 items each
    $.when(
         //List1        WingtipToys.Rest.Lists.create(            "Announcements1",            "The first Announcements List",            SP.ListTemplateType.announcements),
         //List2        WingtipToys.Rest.Lists.create(            "Announcements2",            "The second Announcements List",            SP.ListTemplateType.announcements),
     ).done(
             function (x1, x2) {
                         //Show UI                        $("#mainDiv").show();                        $("#loadingDiv").hide();
             });
});
The first thing to notice is that the code is wrapped in the $(document).ready() method so that it starts execution as soon as the DOM is available. Next, notice that jQuery is used to hide the main part of the app UI and show a loading message to the user. This loading message will stay in place until both of the required lists are created.
The real excitement begins with the $.when() method. This method accepts any number of promises separated by commas. When all of the promises are resolved, the done() method fires. In our example, the two promises are the return values from separate calls to the create() function in the library. When both of these promises resolve, jQuery is used to display the app’s UI because it is now ready for the user.
Note that the completion function contained within the done() method has two parameters (x1 and x2). This function will have a return parameter for each promise, which can be used to retrieve the return data from the async operation. When coding this function, simply add additional parameters to the function so that the return parameters match one-to-one with the promises. You can then read information about the created lists from the parameters using code such as this:
var title1 = x1[0].d.Title;var title2 = x2[0].d.Title;var type1 = x1[0].d.ListItemEntityTypeFullName;var type2 = x2[0].d.ListItemEntityTypeFullName;
Take advantage of the when…done pattern whenever you need to execute multiple async calls in parallel and perform a function only after all of them are resolved successdfully.

How to create App Part in SharePoint 2013

Copyright from: jeffreypaarhuis.com
The App Part in SharePoint 2013 is actually a Web Part version of an App. Like Web Parts in 2010 they reside in a small frame on the page. For the old Web Part this was some rendered ASPX, for an App Part this is an HTML-page in an IFrame.
In this post I want to explain, very shortly how to create an SharePoint-hosted App Part.

Build the App Part

I assume you have a developer site collection. If you haven’t yet, you can create one by selecting the Developer Site template under the Collaboration tab when creating a new site collection. This site collection has some build-in functionality that helps you deploy Apps from Visual Studio.
Ok, start off by creating a new SharePoint App in Visual Studio.  The App will be the container for the App Part.
Create an App with Visual Studio
In this scenario we are building a SharePoint-hosted App (Part) which means we can only use client-side code. If you want to know more about the different hosting options, please read this overview on MSDN.

Select App hosting options

Visual Studio creates an App with an hello-worldish script in the App.js. This script retrieves the display name of the current user and puts it in the 
 on the default App page Default.aspx.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
'use strict';
 
var context = SP.ClientContext.get_current();
var user = context.get_web().get_currentUser();
 
// This code runs when the DOM is ready and creates a context object which is needed to use the SharePoint object model
$(document).ready(function () {
 getUserName();
});
 
// This function prepares, loads, and then executes a SharePoint query to get the current users information
function getUserName() {
 context.load(user);
 context.executeQueryAsync(onGetUserNameSuccess, onGetUserNameFail);
}
 
// This function is executed if the above call is successful
// It replaces the contents of the 'message' element with the user name
function onGetUserNameSuccess()
 $('#message').text('Hello ' + user.get_title());
}
 
// This function is executed if the above call fails
function onGetUserNameFail(sender, args) {
 alert('Failed to get user name. Error:' + args.get_message());
}
You can run this app now and see that Visual Studio deploys the app to your developer site and starts debugging it.
Plain App
Did you know that you can debug your JavaScript straight in Visual Studio without the need of browser developer tools
We now add a Client Web Part item to the project. Despite of being called a Client Web Part, this will be the App Part.
Add Client Web Part
We want the wizard to create a new page for the App Part.
Create App Part page
This creates a Client Web Part and a page.
App Part Created
We can change the properties of the App Part, like the title, by modifying the Elements.xml.
When you open the App Part ASPX page you will notice that it looks different compared to the Default.aspx. Where the Default.aspx is using the SharePoint master page, the App Part Page is an empty page with no master page whatsoever. This is because the App Part Page will be shown in an IFrame, so we need an empty page. The only code Visual Studio generates out of the box are some JavaScript references and a script that will reference the right CSS.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
Now let’s create the same hello-worldish script on this page. Therefor we need the following script reference in the header:
1
And the following markup in the body:
1
2
3
4
5
6
<div>
 <p id="message">
  
  initializing...
 </p>
</div>
Run the App again, go to the developer site and add the App Part to the page.
Add App Part to page
Finally it would look something like this.
App Part on page
Happy coding!