Cum Grano Salis : EwaCompanion

EWA Companion Part 4: Refresh/Recalc functionality

Shahar — Wed, 22 Aug 2007 19:10:55 GMT

In the first part of this post series I showed the EWA companion and its various capabilities. In this part, I will delve deeper into the "Automatic Refresh/Recalc" capabilities of the companion.

This feature is divided into two parts - refresh and recalc. Refresh is mostly only useful when your workbook contains a Pivot-Table that's not based on external data. Since the Excel Services feature of Periodic Refresh is a property of an Excel connection, there's nowhere to set it for PivotTables that are based on data inside Excel.

The Calculate option is mostly useful if your workbook contains volatile formulas (such as =NOW()). This will allow the workbook to refresh periodically.

To enable this feature, you need to go to the companion's properties and decide which of these you want:

You can set up either operation you want (or both). You can also set the interval (in seconds) the EWA will use to refresh.

Once this is set up, you are pretty much done. Once every N seconds, the browser will issue AJAX calls to refresh/recalc the workbook and refresh the page. Note that as opposed to the previous features, there is no visual cue on the Companion web-part to show that something is happening.

The Code

On the server side, the code that controls this feature is pretty simple. All it does is inject some javascript into the page:

if (!DesignMode && RefreshPeriodically || RecalcPeriodically)

{

int flags = 0;

if (RefreshPeriodically)

{

flags |= 1;

}

if (RecalcPeriodically)

{

flags |= 2;

}

string scriptlet = String.Format(

"EcIssueRefreshRecalcPeriodically('{0}', {1}, {2});",

ConnectedEwa.ClientID,

flags,

RefreshInterval * 1000);

Page.ClientScript.RegisterStartupScript(this.GetType(), ClientID + "_ForRefreshRecalc", scriptlet, true);

}

What this does is add code that calls the EcIssueRefreshRecalcPeriodically js function. The number that is passed in as the second parameter governs what needs to be done (1 - refresh, 2 - recalc, 3 - both).

The js function simply uses the setTimeout method to defer the call to whatever timeout was given by the properties of the web-part:

function EcIssueRefreshRecalcPeriodically(id, flags, interval)

{

window.setTimeout("EcRefreshRecalcPeriodically('" + id + "', " + flags + "," + interval + ");", interval);

}

This method will issue the EcRefreshRecalcPeriodically when the timeout is reached:

function EcRefreshRecalcPeriodically(id, flags, interval)

{

var sessionId = EwaGetSessionId(id);

if (sessionId == null)

{

EcIssueRefreshRecalcPeriodically(id, flags, 5000);

return;

}

var es = new ExcelServices();

var info = new EcRefreshRecalcState();

info.sessionId = sessionId;

info.flags = flags;

info.es = es;

info.wpid = id;

info.interval = interval;

es.setUserState(info);

if (info.flags & 1)

{

EcRefreshAll(info);

}

else if (info.flags & 2)

{

EcRecalc(info);

}

This is where things get funky. What we do here is create an object that contains a bunch of information and we then issue an AJAX request to the server using the Excel Services AJAX library.

Depending on the flags, we either call the EcRefreshAll() or the EcRecalc() method. The helper object (EcRefreshRecalcState) contains all our state, including the Excel Services object (the .es property).

Next, take a look at the EcRefreshAll() method:

function EcRefreshAll(info)

{

info.es.refreshAll(info.sessionId, EcRefreshComplete);

}

function EcRefreshComplete(webMethod)

{

var info = webMethod.excelServices.userState;

if (info.flags & 2)

{

EcRecalc(info);

}

else

{

EcRefreshIFrame(info);

}

The method calls the Excel Services AJAX wrapper called "refreshAll", passing it a callback called EcRefreshComplete. Once the Refresh is complete, it uses the userState property to continue the call (if needed - depending on the flags). Then either EcRecalc will be called (which issues the Recalc method on the Excel Services AJAX object), or the EcRefreshIFrame is called (which refreshes the browser to show the new results).

That's about it for this series of posts. If I add functionality to this library, I will add posts that explain it. If you have any questions, feel free to use the blog or our forums to post them.

EWA Companion Part 3: Open/Download functionality

Shahar — Tue, 21 Aug 2007 19:11:15 GMT

In the first part of this post series I showed the EWA companion and its various capabilities. In this part, I will delve deeper into the "Open" functionality of the EWA Companion web-part.

There are a few reasons behind adding the Open command to the EWA. While the functionality already seemingly exists in it (You can use the "Open" menu on EWA to open the active session inside Excel 2007), but some things are missing. For one, the "Open" menu only works with Excel 2007. If you have Excel 2003 or below installed with the compatibility pack, you will not be able to use that functionality. Another thing that is impossible to do today is to immediately Save As the workbook (you need to go to Excel 2007, and then choose Save As from there). Lastly, I have heard some users request printing functionality. While printing from the browser never really works that well, Microsoft does distribute a free Excel Viewer. Using this functionality, it should be possible to view and print Excel files without needing to install Excel on the client (of course, your functionality will be very diminished, but at least you should be able to print/view files outside of the browser).

To enable the Open feature, you need to go to the properties of the web-part and add them:

Once enabled, you will see the following menu item in the web-part:

Once clicked, you will get the regular IE/Firefox download dialog box:

This can then be used for whatever you want - clicking "Open" will run the default app (Excel 2003 for example). Clicking "Save" will give the save dialog.

The Code

There are 2 parts for the code for this portion of the companion. The first one is the ASPX page that actually allows you to get the file from the server and the second is the EWA companion code that invokes that page.

First, take a look at the ASPX page code-behind - the Load functionality:

protected override void OnLoad(EventArgs e)

{

base.OnLoad(e);

try

{

m_sessionId = Request.QueryString[SessionIdParam];

string wt = Request.QueryString[WorkbookTypeParam];

if (wt.Equals(WorkbookTypeFull, StringComparison.OrdinalIgnoreCase))

{

m_workbookType = WorkbookType.FullWorkbook;

}

else if (wt.Equals(WorkbookTypeSnap, StringComparison.OrdinalIgnoreCase))

{

m_workbookType = WorkbookType.FullSnapshot;

}

else if (wt.Equals(WorkbookTypePublished, StringComparison.OrdinalIgnoreCase))

{

m_workbookType = WorkbookType.PublishedItemsSnapshot;

}

catch (Exception ex)

{

m_error = ex;

}

In here, the code simply takes the parameters and determines what the operation that needs to be done is. The actual code that streams the workbook back to the user is in the Render override:

protected override void Render(HtmlTextWriter writer)

{

if (m_error != null)

{

writer.WriteLine(m_error.ToString());

return;

}

try

{

ExcelService s = new ExcelService();

Status[] status;

byte[] bits = s.GetWorkbook(SessionId, WorkbookType, out status);

Response.Clear();

Response.AddHeader("LAST-MODIFIED", DateTime.Now.ToString("r"));

Response.Charset = "";

Response.ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";

Response.OutputStream.Write(bits, 0, bits.Length);

Response.OutputStream.Flush();

}

catch (Exception ex)

{

writer.WriteLine(ex.ToString());

}

Response.End();

}

The main part here is the GetWorkbook() call which takes the binary representation of the workbook. The second part is stuffing the file into the Response and making sure that it will get opened by the appropriate application on the client (that's what the ContentType property governs).

Finally, the companion invokes this page by using client-script. Here is the piece of code that gets attached to each of the "Open" menu items:

private void AddOpenButton(string text, string type, System.Web.UI.WebControls.MenuItem sub)

{

System.Web.UI.WebControls.MenuItem item = new System.Web.UI.WebControls.MenuItem(text);

sub.ChildItems.Add(item);

item.NavigateUrl = String.Format(

"javascript:EcOpenExcelWorkbook('{0}','{1}');",

ConnectedEwa.ClientID,

type);

}

All this does is call the JavaScript function EcOpenExcelWorkbook(). That's defined inside the EwaCompanionScripts.js file:

function EcOpenExcelWorkbook(wpid, type)

{

var sessionId = EwaGetSessionId(wpid);

if (sessionId == null)

{

return 0;

}

window.location.assign("/_layouts/EcDownloadWorkbook.aspx?sid=" + encodeURIComponent(sessionId) + "&type=" + type);

}

All THIS function does, is get the session id inside the EWA and passes it to the EcDownloadWorkbook.aspx page for processing.

The next part of this series will discuss the last feature in the companion (at this time) which is the periodic refresh.

EWA Companion Part 2: Save As Functionality

Shahar — Mon, 20 Aug 2007 19:00:48 GMT

In a previous post I discussed the EWA companion and how to set it up for saving back to SharePoint. This post will show the next set of capabilities which is the ability to Save As (actually, it exports or saves under another name - the new workbook will not be opened like Save-As usually works).

To set up Save As functionality, the web-page designer needs to check at least one of the Save As Options:

Note that you can choose what options you want to have - Workbook will allow the full workbook to be saved (though it requires full read permissions to the file). Snapshot and Published require less privileges, but do not contain information such as formulas and connections.

Once these are checked, the EWA companion shows up new functionality:

Selecting one of these options un-hides some UI that will allow users to specify the name they want to save as:

The user can now type a name of a file, or click the "Browse" button for help with selecting the document library wanted:

Clicking on the "Save" button will now copy the current workbook as viewed in the EWA into the new file name.

The code

The code for working this is very similar to the code shown in the previous post - the code that saves to SharePoint and the code that gets the workbook was already shown there. The only mildly interesting part here is the code that is generated

First, the code that adds the Save panel to the HTML:

private void AddSaveAsButtons()

{

m_saveAsContainer = new Panel();

Controls.Add(m_saveAsContainer);

m_saveAsContainer.Style.Add(HtmlTextWriterStyle.Display, "none");

Label label = new Label();

m_saveAsContainer.Controls.Add(label);

label.Text = "Save As:";

m_assetPicker = new AssetUrlSelector();

m_saveAsContainer.Controls.Add(m_assetPicker);

m_saveAsTypeTextBox = new TextBox();

m_saveAsContainer.Controls.Add(m_saveAsTypeTextBox);

m_saveAsTypeTextBox.Style.Add(HtmlTextWriterStyle.Display, "none");

m_saveAsButton = new Button();

m_saveAsContainer.Controls.Add(m_saveAsButton);

m_saveAsButton.Text = "Save";

m_saveAsButton.Click += new EventHandler(SaveAsButton_Click);

string scriptlet = String.Format("if (!confirm('{0}')) return;",

"If this file exists, it will be overwritten by the new file. Are you sure you want to proceed?");

m_saveAsButton.OnClientClick = scriptlet;

System.Web.UI.WebControls.MenuItem subMenu = new System.Web.UI.WebControls.MenuItem("Save As");

m_menu.Items.Add(subMenu);

if (ShowSaveAsFull)

{

AddSaveAsButton(subMenu, SaveAsFull, "Save Workbook");

}

if (ShowSaveAsSnapshot)

{

AddSaveAsButton(subMenu, SaveAsSnapshot, "Save Snapshot");

}

if (ShowSaveAsPublished)

{

AddSaveAsButton(subMenu, SaveAsPublished, "Save Published Items");

}

The code adds a panel to the HTML, hides it and then fills it up with a label, an Asset Picker and a button. The button's OnClick event is hooked to the SaveAsButton_Click(). The function also adds menu items depending on what options were selected by the user by using the AddSaveAsButton() method:

private void AddSaveAsButton(System.Web.UI.WebControls.MenuItem subMenu, string type, string text)

{

System.Web.UI.WebControls.MenuItem item = new System.Web.UI.WebControls.MenuItem(text);

subMenu.ChildItems.Add(item);

string scriptlet = String.Format(

"javascript:document.getElementById('{0}').value = EwaGetSessionId('{1}'); document.getElementById('{2}').value = '{3}'; EcShowSaveAsDialog('{4}');",

m_sessionIdTextBox.ClientID,

ConnectedEwa.ClientID,

m_saveAsTypeTextBox.ClientID,

type,

m_saveAsContainer.ClientID);

item.NavigateUrl = scriptlet;

}

The code adds an event to each of the save-as buttons - depending on what the button is, it will set up a different type inside the input - that will determine how GetWorkbook() will be called later. The code also sets up the session id into the appropriate hidden field.

Here's what the Save event handler looks like:

void SaveAsButton_Click(object sender, EventArgs e)

{

try

{

string typeString = m_saveAsTypeTextBox.Text;

WorkbookType type = WorkbookType.FullWorkbook;

if (typeString == SaveAsSnapshot)

{

type = WorkbookType.FullSnapshot;

}

else if (typeString == SaveAsPublished)

{

type = WorkbookType.PublishedItemsSnapshot;

}

byte[] bits = GetWorkbookBits(type);

using (SPSite site = new SPSite(ConnectedEwa.WorkbookUri))

using (SPWeb web = site.OpenWeb())

{

SPFile file = web.GetFile(m_assetPicker.AssetUrl);

file.SaveBinary(bits);

SetMessage("Save succeeded!");

}

catch (UserException u)

{

SetMessage("Save failed: " + u.ToString());

}

catch (Exception ex)

{

SetMessage("Unknown save failure:" + ex.ToString());

}

The click event kicks off the following code:

void SaveAsButton_Click(object sender, EventArgs e)

{

try

{

string typeString = m_saveAsTypeTextBox.Text;

WorkbookType type = WorkbookType.FullWorkbook;

if (typeString == SaveAsSnapshot)

{

type = WorkbookType.FullSnapshot;

}

else if (typeString == SaveAsPublished)

{

type = WorkbookType.PublishedItemsSnapshot;

}

byte[] bits = GetWorkbookBits(type);

using (SPSite site = new SPSite(ConnectedEwa.WorkbookUri))

using (SPWeb web = site.OpenWeb())

{

SPFile file = web.GetFile(m_assetPicker.AssetUrl);

file.SaveBinary(bits);

SetMessage("Save succeeded!");

}

catch (UserException u)

{

SetMessage("Save failed: " + u.ToString());

}

catch (Exception ex)

{

SetMessage("Unknown save failure:" + ex.ToString());

}

As you can see, the code is very similar to the what the Save button does in the previous post. Instead of saving back though, it saves into an existing file.

The next post will discuss the Open menu item.

Introducing EWA companion: A web-part that adds missing functionality to the EWA component

Shahar — Fri, 17 Aug 2007 19:15:03 GMT

Download the Ewa Companion

Over the past year or so, some requests have been voiced by the community again and again. Some of these related to the EWA, asking for extra functionality that is not there by default. To that extent, I decided to write the EWA companion which contains some of the functionality that has been requested by users.

Important note: I am not an HTML/JS programmer. At best, I stumble around, trying to make things work. At worse.. Well.. Lets not talk about that. My HTML stuff tends to look like crap. On top of that, this code is intended to be sample code. I only have rudimentary error checking and some code-paths have not been tested very well.

The EWA companion introduces the following functionality:

Save capabilities - save back to the file that is currently opened in Excel Services.
Save As capabilities - save the workbook into a new location (document library in SharePoint)
Open/Download capabilities - these allow the user to download the currently opened workbook to the client. The extra functionality here is that the user does not have to open Excel to do that. On top of that, this will allow Excel 2003 (and prior) to open the workbook. Furthermore, if you have the Excel Viewer installed, the workbook can be opened automatically there as well.
Periodic Refresh/Recalc - When workbooks contain volatile formulas (=NOW for example, or some volatile UDF), it is sometimes desirable to allow them to periodically recalculate and refresh the HTML to show the new results. Furthermore, it is sometimes useful to be able to periodically refresh pivot-tables that are not connected to external data sources, but rather, to data on an Excel sheet - something EWA cannot do today.

Today's post concentrates on setting up the EWA Companion itself and enabling the "Save" functionality.

Once set up, you can simply add the companion to the page just like you could any other web-part:

Once added, the companion needs to be connected to an EWA. Currently, the options you have is to place an EWA above or below the companion. You can then control what the companion connects to by modifying the "Controlled EWA" property in the Companion's properties.

In the following image you can see a web-part page in design mode with 4 points of interest:

1 - This is the EWA companion. As you can see, it is "selected" and so the properties pane at the right shows its properties.

2 - This is the EWA itself - it is currently not set up to show any workbook.

3 - Properties Category for the companion - This category contains all the properties that the companion supports.

4 - The Controlled EWA property - this is the one that governs which EWA is controlled. Currently, the value is "Next" which means that the EWA below the companion will be controlled. Note that if the companion was to be below the EWA, this property should have shown "Previous".

Next, I will show you how a set-up page looks. This time, there will be a book selected inside the EWA and the companion would have been set up to only show the "Save" menu option:

Clicking on the "Save" menu item shows up a warning. Once "OK" is clicked, the workbook as it is in EWA will be saved back to SharePoint, overwriting the workbook that is currently there. Since there's no locking taking place, you may end up overwriting somebody else's changes.

How does it work?

(Note that I am not going into complete details here, just showing the jist of the functionality - the full source code is supplied with the binary)

The save functionality goes through the following steps:

In the server, the companion detects what EWA it is connected to - this is done everytime the control is created.
On the client, when "Save" is clicked, script runs that takes the session-id of the EWA and posts it back to the companion web-part.
The companion web-part then calls the Excel Web Services API's GetWorkbook function, getting the stream of bytes that represents the workbook.
Next, the companion takes the stream and the name of the workbook the EWA is pointing to and uses SharePoint APIs to write the stream back to the document library.

Connecting to the EWA

This is done on the server, in the web-part code:

private void ConnectToEwa()

{

ExcelWebRenderer result = null;

if (ConnectMode == ConnectMode.Next || ConnectMode == ConnectMode.Previous)

{

int delta = (ConnectMode == ConnectMode.Next) ? 1 : -1;

int index = ZoneIndex + delta;

object webPart = Utils.WebPartFromZone(Zone.WebParts, index);

result = webPart as ExcelWebRenderer;

if (webPart == null)

{

throw new InvalidConnectionException("Could not find a control to affect. Please check the 'Controlled EWA' property in the companion properties");

}

else if (result == null)

{

throw new InvalidConnectionException("The control that is set up to be connected to the companion is not an EWA. Please check the 'Controlled EWA' property.");

}

else

{

throw new InvalidConnectionException("This connection is not currently supported. Choose either 'Next' or 'Previous' in the 'Controlled EWA' property.");

}

m_connectedEwa = result;

}

What this code does, is use the Utils class method WebPartFromZone (shown below) to find the next or previous web-part. The Zone property allows for easy access to the Web-Part page zone the EWA companion is currently located in.

static class Utils

{

public static WebPart WebPartFromZone(WebPartCollection collection, int zone)

{

WebPart result = null;

foreach (WebPart webPart in collection)

{

if (webPart.ZoneIndex == zone)

{

result = webPart;

break;

}

return result;

}

As you can see, the way this method works is by using the ZoneIndex to look for the relevant Web-Part. ZoneIndex is not necesserily aligned with the actual index of the element in the WebParts collection of the Zone object.

Adding the Save button

Now that we have a reference to EWA (inside the m_connnectedEwa field which is accessible through the ConnectedEwa property), we can use it to build the script that will run when we click the "Save" button:

private void AddSaveButton()

{

System.Web.UI.WebControls.MenuItem item = new System.Web.UI.WebControls.MenuItem("Save");

m_menu.Items.Add(item);

string postBack= Page.ClientScript.GetPostBackEventReference(this, SaveCommand);

string scriptlet = String.Format(

"javascript:if (confirm('{0}')) {{ document.getElementById('{1}').value = EwaGetSessionId('{2}');{3}; }};",

"Saving this file will overwrite any changes that have been made since you last opened it. Are you sure you want to proceed?",

m_sessionIdTextBox.ClientID,

ConnectedEwa.ClientID,

postBack);

item.NavigateUrl = scriptlet;

}

As you can see, the Save button (actually, as ASP.NET menu item) gets a javascript block attached to it. What the Javascript does, in essence, is confirm with the user that they indeed want to save (that's the call to the confirm() method). It then assigns a value to a hidden text-field we have on the web-part (that's the m_sessionIdTextBox - it is created as part of the web-part). And lastly, it issues a post-back to the web-part (the post-back was generated by a call to GetPostBackEventRefernece()).

Saving the workbook to SharePoint

What this does, in a nut-shell, is to take the session id that the EWA is currently using and post it back to the server, with the "Save" command. This is where the save command is processed:

public void RaisePostBackEvent(string eventArgument)

{

if (eventArgument == SaveCommand)

{

SaveButton_Click();

}

void SaveButton_Click()

{

try

{

byte[] bits = GetWorkbookBits(WorkbookType.FullWorkbook);

using (SPSite site = new SPSite(ConnectedEwa.WorkbookUri))

using (SPWeb web = site.OpenWeb())

{

SPFile file = web.GetFile(ConnectedEwa.WorkbookUri);

file.SaveBinary(bits);

SetMessage("Save succeeded!");

}

catch (UserException u)

{

SetMessage("Save failed: " + u.ToString());

}

catch (Exception ex)

{

SetMessage("Unknown save failure:" + ex.ToString());

}

The SaveButton_Click() method calls the GetWorkbookBits() method, asking for the full workbook (since that's what we are interested in when we save) and then makes calls to the SharePoint APIs to save the workbook back to the document library.

Getting the workbook bits from Excel Services

This is what GetWorkbookBits() looks like:

private byte[] GetWorkbookBits(WorkbookType type)

{

try

{

ExcelService s = new ExcelService();

Status[] status;

byte[] bits = s.GetWorkbook(m_sessionIdTextBox.Text, type, out status);

return bits;

}

catch (SoapException soapEx)

{

string code = soapEx.SubCode.Code.Name;

if ("InvalidOrTimedOutSession".Equals(code, StringComparison.OrdinalIgnoreCase))

{

throw new UserException("The session has timed out.");

}

else

{

throw new UserException("Could not save the workbook (probably due to permissions).");

}

In here, we make a call to the Excel Web Services APIs to get the binary representation of the workbook (a byte array) which we then simply return to the caller.

That's about it for Save. In the next post I will show how the Save-As functionality works and how it was coded.