May 23

Written by: Michael Washington
5/23/2013 5:55 AM 

To maximize performance, all applications must properly manage the flow of data. When dealing with an entity (one row of data), Visual Studio LightSwitch transfers the entire entity from the data layer to the client, the user interface (UI) layer. When dealing with collections (rows of data) LightSwitch uses Visual Collections, and is very deliberate as to how, and when it places entities in the Visual Collection.

The key thing to note is that LightSwitch will page the data. Meaning, it will not load all the data at one time. In our example, we have set the paging to 5 items at a time. However, when we run the application, it will typically display over 50 records when it starts.

When we do a network trace of the running application, we see that it makes multiple requests, 5 records at a time.

The Visual Collection API

The Visual Collection API allows the LightSwitch developer the ability to programmatically detect and manage the flow of data.

LightSwitch team member Huy Nguyen provides the following explanation of the Visual Collection API using a hypothetical Customers collection:

• screen.getCustomers() will return a Promise object that will be fulfilled when the Customers Visual Collection is loaded. This is the one exposed under Intellisense, because most of the time it's what you want to use.
• screen.Customers will return the Visual Collection representing the Customers on the screen. This is hidden from Intellisense because when you access it, it's not guaranteed that the Visual Collection is loaded. But it's useful to set up change listener, etc.
• screen.Customers.data will return an array of all Customers loaded into the Visual Collection.
• screen.Customer.selectedItem will return the current selected Customer in the Visual Collection.

 

screen.getCustomers() and screen.Customers.data

This first example will look at the .get method that returns a Promise object for the collection.

This example will also show how we can iterate through the entities returned by the Promise object using the .data property.

To set up the example, we add a Customer entity (a single Customer) to the View Model. We will call it LatestLoadedCustomer (right now it is just empty). We create a Popup and we drag the LatestLoadedCustomer entity to the Popup so that it will show when we open the Popup.

We create a button and use the following code:

 

myapp.BrowseCustomers.CallGetCustomers_execute = function (screen) {
    // Call getCustomers
    screen.getCustomers().then(function (result) {
        var index = result.data.length; // gets length of the full Customer array
        // The last Customer found in the 
        // collection will be 
        // set to LatestLoadedCustomer
        screen.LatestLoadedCustomer = result.data[index - 1]; // compensate for 0-based index
        // Show the Popup to display 
        // LatestLoadedCustomer
        screen.showPopup("LatestCustomer");
    });
};

 

When re run the application and click the button…

The last record retrieved by the method is displayed.

 

screen.Customers

While it is not guaranteed to be loaded, the Visual Collection allows us to easily attach handlers so that our code will run when the Visual Collection is loaded with data.

In this example we click on the Tile List that is bound to the Customer collection, and select Edit PostRender Code.  

We use the following code:

 

myapp.BrowseCustomers.Customer_postRender = function (element, contentItem) {
    // Set up a databind on screen.Customers.count
    contentItem.dataBind("screen.Customers.count", function (newValue) {
        // Update the total records display
        DisplayCustomerCount(contentItem.screen);
    });
};
// Utility
function DisplayCustomerCount(screen) {
    // If there is a Customer collection
    // display the current count
    if (screen.Customers != undefined && screen.Customers != null) {
        var strDisplayText = "Loaded Customers: " + screen.Customers.count;
        screen.details.displayName = strDisplayText;
    }
}

 

When we run the application we see that the number of loaded Customers will display.

We can also add the following code to the method:

 

    // Set up a databind on screen.Customers.selectedItem
    contentItem.dataBind("screen.Customers.selectedItem", function (newValue) {
        var SelectedItem = newValue;
        // do we have a selected Customer?
        if (SelectedItem != undefined && SelectedItem != null) {
            // Update the display to show the last selected Customer
            var strDisplayText = "SelectedItem CustomerName: " + SelectedItem.CustomerName;
            contentItem.screen.details.displayName = strDisplayText;
        }
    });

 

When we run the application and click on an Customer, the name of Customer will display in the title.

 

Manual Paging

In the previous examples, we loaded more records by scrolling down through the Tile List. We can also programmatically control the paging  by manually loading records into the Visual Collection.

We create a button…

We use the following code:

 

myapp.BrowseCustomers.GetMoreRecords_execute = function (screen) {
    if (screen.Customers.canLoadMore) {
        // We can load more records -- load them
        screen.Customers.loadMore().then(function (result) {
            var index = result.items.length; // gets length of the full Customer array
            // The last Customer found in the 
            // collection will be 
            // set to LatestLoadedCustomer
            screen.LatestLoadedCustomer = result.items[index - 1]; // compensate for 0-based index
            // Show the Popup to display 
            // LatestLoadedCustomer
            screen.showPopup("LatestCustomer");
            // Update the total records display
            DisplayCustomerCount(screen);
        });
    }
};

 

When we run the application and click the Get More Records button…

Additional records will be loaded into the Visual Collection, and the last record loaded will be displayed.

Note: For more advanced paging, see: LightSwitch HTML Client For The Desktop Web Browser.

 

Special Thanks

A very special thanks to LightSwitch Team member Huy Nguyen.

Download Code

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

(you must have Visual Studio 2012 Update 2 installed to run the code)