Enable SharePoint Client App Parts to Post Status and Notification Alerts to Host Page

Office365, SharePoint, Technology
by on
Status and Notification from Client App Parts. ↔

This post will show you how to opt-in to enabling Client App Parts from Apps for SharePoint to post Status Bar and Notification area alerts to the hosting page.

Overview

Client App Parts are essentially iframes that can be placed on SharePoint pages. Because Apps for SharePoint run in a different domain name than the host web, Client App Parts are by default restricted from accessing anything on the host page. This makes them pretty “dumb” islands on the page, as they can’t be aware of anything on the host page, and can’t interact with host page elements through the DOM.

This post will show how you can use the postMessage api to enable your Apps for SharePoint to write Status Bar and toaster Notification alerts to the hosting page.

Creating the SharePoint App

For this demonstration, I’m going to use a simple SharePoint-hosted app, but the following will also work with a Provided-hosted app part as well. I’ll start by creating a new SharePoint-hosted app, called StatusBarApp, and then add a Client Web Part to the project, called StatusBarAppPart, with a new page called StatusBarAppPart.aspx:

App Part Project.

The basic solution structure.

I’ll open up StatusBarAppPart.aspx and add a reference to my App.js file:

I’ll add the following markup to the page in the <body>:

Basically it’s two buttons that I can use to add status and notification alerts to the hosting page.

After that, I’ll switch to the App.js file, and replace the contents with the following code:

I’ll deploy the app, and place the Client App Part on a host-web web part page:

App Part in Host Page.

The client app part rendering in the host page.

Right now, the buttons will send postMessages, but nothing will happen. You’ll notice that I am sending the message over as a stringified version of a JSON object. This can then be rehydrated on the hosting page as a valid JSON object. In the next section, I’ll add the receiving code and wire everything up.

Adding the Opt-In Code to the Host Page

Using postMessage is a two-sided handshake. One side can send messages, but if the recipient isn’t listening for them, the messages are completely ignored. In order to have the host page receive the messages from the App Part, some script needs to be placed on the host page to listen and respond accordingly. This script I am going to place in a ScriptEditor web part. The following snippet will make the host page listen for the messages, and create status and notification alerts:

With this code in place, I can now click the buttons, and see new status messages and toaster notifications on the host page:

Working App Part.

Cool, right?

To make this even better, you can implement the operations to remove status, update/append status, and clear notifications, using postMessage actions from the host page to the App Part iframe, sending back the status or notification ids (the reverse direction of what was configured above).

Securing Messages

When you use postMessage to send cross-domain messages between iframes and windows, you have the potential of letting malicious code get sent and executed. To prevent this, you’ll need to harden the messaging system and throw away invalid messages. To see an example of this hardening, let’s take a look at how SharePoint itself manages the security for its built-in resize postMessage handler. Following you can see the code that gets added to a host page whenever it contains at least one Client App Part on the page:

Notice the first line and last line. The first line declares an array (spAppIFrameSenderInfo) with a specific size. This array size will vary depending on how many Client App Parts are on the hosting page. For each Client App Part, there will be a corresponding item in this array.

Now notice the last line. A line like this is injected on the page for each Client App Part placed on the page, adding specific information about that App Part into the array declared earlier.

In the array item representing the App Part, you’ll notice an odd value for the first parameter of the array item. This is a unique alphanumeric number that is dynamically generated fresh on every page request. This value is passed to the Client App Part via the SenderId querystring parameter (if you use the StandardTokens). This SenderId has a couple of parts to it – the first 8 characters are an alphanumeric string randomly generated. Any characters after that represent the index inside of the spAppIFrameSenderInfo array.

Now let’s start looking at the hoops Microsoft has gone through just to ensure that a resize message is secure. First, you’ll notice that Microsoft is using an XML string to pass information across postMessage. Why not JSON here? I can’t speak for Microsoft, but my assumption is that they chose this route because they were worried about malicious code in a JSON object getting rehydrated and executed on the other side. The JSON.parse function in modern browsers is designed to ensure safe execution, and takes a number of steps to make sure that malicious javascript isn’t just blindly executed with an eval() statement. My take: it’s good to be extra cautious, but if you are running a controlled environment with your own SharePoint apps (and tightly controlling where and what 3rd party apps are installed), passing JSON is much easier to deal with than parsing XML.

Next, Microsoft checks to make sure that the entire message isn’t longer than 100 characters:

Next, Microsoft parses the entire message using RegEx, and a host of capture phrases to extract all of the relevant data it needs:

One of the things it captures is the SenderId, which is required to be passed back by the App Part. The SenderId is split into its two parts, and then the second part checked to ensure that it isn’t outside the bounds of the spAppIFrameSenderInfo array:

Next, the code checks to make sure that the SenderId passed matches the SenderId in the spAppIframeSenderInfo array for the item at the specified index. This ensures that the resize message fires for the correct App Part that sent the message, and only that App Part:

You can see that the validation here is quite intense, just to get a resize message across. Using similar validation approaches, I can now harden the earlier code in the ScriptEditor web part, to be more secure:

Summary

Hopefully I’ve shown how you can use postMessage api to enable Client App Parts to interact with the host page and post Status and Notification items. You can further expand this concept to other things, like popping up Modal Dialogs, displaying Wait Dialogs or loading indicators, or other interactive parts of the SharePoint host page.

2 comments on “Enable SharePoint Client App Parts to Post Status and Notification Alerts to Host Page”

  1. Do you know what creates the settings for the Array


    spAppIFrameSenderInfo[0] = new Array("04885D9A0","g_a32cdeb7_500b_4d41_96bd_99b968b8fdaa","https:\u002f\u002fdomainnameremoved-b84e6d0e047207.sharepoint.com","True","False","ctl00_ctl34_g_06e70b34_2f05_400a_a8c7_e6a17ec59506");

    I am specifically looking for the
    spAppIFrameSenderInfo[senderIndex][3]
    and the
    spAppIFrameSenderInfo[senderIndex][4]

    values. In my source, they are both set to True. When the when this line executes
    var resizeWidth = ('False' == spAppIFrameSenderInfo[senderIndex][3]);

    it doesn’t re-size the frame.

    Am I missing something here?

  2. Writing my last comment a minute ago sparked something in my brain I guess.

    The problem was that I set width and height to be fixed inside the edit part settings.

    I changed the height and width back to the “Fit to zone” option and my postMessage Script worked.

    Thank you for this article, it was well written and very helpful.

Comments are closed.