New API For Refreshing Data in LightSwitch in Visual Studio 2013

Yesterday Visual Studio LightSwitch was released in a preview of Visual Studio 2013.

You can get it here: http://www.microsoft.com/visualstudio/eng/2013-downloads. You can read more about the new features here: http://blogs.msdn.com/b/lightswitch/archive/2013/06/27/announcing-lightswitch-in-visual-studio-2013-preview.aspx.

One new feature is described as: API support for refreshing data on lists and screens in the runtime app. That is the feature we will explore here.

The Sample Project

We start with the application created in the tutorial: An End-To-End Visual Studio LightSwitch HTML5 Application.

When we open it up, it will be converted to the new Visual Studio 2013 format. However, to get it to run we have right-click on the first project…

…and set it as the startup project.

The API

The new refresh() API consists of  two methods that each return a Promise object.

refresh() Asynchronously loads the first page of items into this collection and
returns a promise that will be fulfilled when the first page is loaded.
Existing results will be refreshed on the first page and subsequent
pages unless load() is called again. refresh(navigationPropertyNames) Updates the entity with values from the data source if the entity
is not changed.
An array of names of navigation properties to be included. An empty
array means no properties will be included. If not specified, all
reference properties are included. Sample usage Refresh the Order entity and its Customer, Employee, Shipper screen.Order.details.refresh(); Refresh only the Order entity screen.Order.details.refresh([]); Refresh the Order entity and its Customer screen.Order.details.refresh(["Customer"]);

The Problem

Let’s say we have a field on the Order entity that is updated in the save pipeline when an associated OrderDetail record is updated.

In the OrderDetail record, the updating event looks like this:

 

 

We can update an OrderDetail record…

.. save the changes…

…but the time is unchanged on the screen (even though it has been updated in the database).

If we refresh the web browser…

…we now see the properly updated time.

 

The Solution

We can instantly have the entity updated if we use the new refresh() method.

To do so requires us to implement our own code to open the edit screen (so we have an opportunity to implement the refresh code).

We select the Item Tap action for the Orders list.

We select Write my own method.

We then edit the code for the method we created.

We use the following code:

 

myapp.Main.Order_ItemTap_execute = function (screen) {
myapp.showAddEditOrder(null, {
beforeShown: function (addEditOrderScreen) {
// Set the Order on the AddEditOrder screen
// to the selected Order on the Main screen
addEditOrderScreen.Order = screen.Orders.selectedItem;
},
afterClosed: function (addEditScreen, navigationAction) {
// If the user commits the change,
// update the selected order on the Main screen
if (navigationAction === msls.NavigateBackAction.commit) {
// *****************************************
// The .refresh() method refreshes the Order
screen.Orders.selectedItem.details.refresh();
}
}
});
};

 

When we update the record we will see the date instantly updated without the need to refresh the entire screen.

To have the entity automatically refreshed, LightSwitch would need to implement datajs 1.1.1. This may happen by the time Visual Studio 2013 is fully released.

For now, the work around is to call the refresh() method as we have shown above.

Behind the Scenes

What the new refresh API does is execute a query using the unchanged-only merge option. In the previous version of LightSwitch, it used the append-only merge option:

Append only: This is the only option in previous version and still the default behavior of query execution.


Entities that do not exist in the data workspace are added to the data workspace. If an entity is already in the data workspace, the current and original values of the entity's properties are not overwritten with data source values.


Unchanged only: This is the new merge option introduced with VS 2013. It is used for Visual Collection and Entity refresh.


Entities that do not exist in the data workspace are added to the data workspace. If an entity is already in the data workspace and its entity state is unchanged, the current and original values of the entity's properties are overwritten with data source values



Special Thanks

A very special thanks to LightSwitch Team member Huy Nguyen.

Download Code

The LightSwitch project is available at http://lightswitchhelpwebsite.comhttp://lightswitchhelpwebsite.com/Downloads.aspx

(you must have Visual Studio 2013 (or higher) installed to run the code)

More ...Tags: VS2013