Scalar Properties and Collection Properties and Screens! Oh My! – An Overview of Screen Property Actions (Sara Itani)

In the beginning of The Wizard of Oz, the Munchkins urge Dorothy to “follow, follow, follow, follow, follow the Yellow Brick Road!”

Y’know… Dorothy probably wouldn’t have been very happy if the neighboring red brick road turned out to be shorter and/or devoid of lions, tigers, and bears.

Similarly, you probably wouldn’t be very happy if you wasted time implementing a piece of functionality, only to discover an easier way to do it. LightSwitch provides you as a developer ample flexibility to stray from the beaten path, but it also includes plenty of built-in functionality. Like what? Good question. Today, we’ll take a whirlwind tour of all the Screen Property Actions in LightSwitch and Cloud Business App projects that are at your disposal because… well… there are a lot of them, and why not take advantage of what’s available?

Overview

Screen Property Actions help you navigate between screens and/or perform operations within your application. These actions are accessible when you tap on a scalar property (returns entity), collection property (returns collection of entities), or button.

Edit-ItemTap-Action

You can either write your own method (accessible within the scope of the specific screen you’re working with,) or choose an existing method. Existing methods include both those you may have already written for that screen and pre-defined convenience methods that take care of many of the common scenarios you’ll run into while building your application.

What exactly do these mystical convenience methods do? There are four kinds of convenience methods.

  1. Scalar property methods are available within the scope of screens that reference an entity
  2. Collection property methods are available within the scope of screens that reference an entity collection
  3. Screen methods are available within the scope of a specific screen.
  4. Application methods are available within the scope of the entire application.

Example

Let’s build a small sample application so we can see them in action. We’re going to assume you already know how to create screens in LightSwitch. If you are new to LightSwitch, please read this first.

1. Set up a project to get started

First create a new “LightSwitch HTML Application” project and attach to the Northwind OData service, “http://services.odata.org/Northwind/Northwind.svc”. Select “None” for the Authentication Type, and click through to the next screen. Check “Entities” to include all entities, and press “Finish” to import the selected data items.

Attach-Data-Source-Wizard-NorthwindAttach-Data-Source-Wizard-Entities

Now, right click the Screens folder, and click “Add Screen…” Select the Common Screen Set Template, set the screen data to Products, and check both the “Product Details” and “Product OrderDetails” boxes under “Additional Data to Include.” Press OK to generate a Common Screen Set.

image

You should see two screens – ViewProduct.lsml, and BrowseProducts.lsml (an Add/Edit screen is not generated because the database is read-only.) Also notice that Order_Details collection is included as one of the tabs of the generated ViewProduct Screen because Product has a one to many relationship with Order_Detail and because we checked Product OrderDetails in the New Screen dialog.

Northwind-Order_Details-Product-Relationship

Next add a View Details Screen for Order_Detail. Be sure to check “Use as Default Details Screen.”

Add-New-Screen-ViewOrder_Detail

Take a look at Solution Explorer. You should now have three screens – BrowseProducts.lsml, ViewProduct.lsml, and ViewOrder_Detail.lsml – as shown below.

Solution-Explorer-Result

Hit F5 to launch the app and start debugging. Click through the screens to see what you built – every navigation is brought to you by Screen Property Actions automagically wired up by the Common Screen Set template.

BrowseProducts-Runtime

2. Follow, follow the ItemTap actions

Pop quiz. What happens when you click on one of the items in the Order Details tab in the ViewProduct Screen? That’s right! It navigates to the ViewOrder_Detail Screen.

ViewProduct-Order_Details-TabViewOrder_Detail-Runtime

Let’s dig in and see why that happened. Stop debugging. Click on the Order_Details Tile List in the Order Details tab of the ViewProduct Screen, and locate the Item Tap action in the properties window.

TileList-ItemTap-Hyperlink

Now click the viewSelected hyperlink to edit the action. As you can see, the action navigates to the selected item’s default view screen that we specified during screen creation.

TileList-ItemTap-Dialog 

“Whoa! That’s awesome! It totally read my mind!” you exclaim. “…but what else can we do?” Hmm… I don’t know – let’s try expanding that dropdown list over there.

Edit-ItemTap-Action

Yikes! Wasn’t expecting that. Apparently we have plenty of options… but why???

The following table summarizes the functionality of the methods in the ItemTap Action dialog above. The ViewProduct screen references both the “Product” scalar property and the “Order_Details” collection property (see data members list on left side of screen designer). Therefore the methods specific to these properties are enumerated below their respective headers in the ItemTap Action dialog. The selection of "Navigation" methods, on the other hand, is common to all screens (though their parameters are unique). For clarity, every screen has an associated showScreen application method that allows you a tighter control over your input parameters if you so desire.

  Method Method Type Description Navigate To Property Parameter
Product

Scalar Property Methods

edit Scalar Property Method Navigate to Product ‘edit’ screen Specify screen Inferred
view Scalar Property Method Navigate to Product ‘view’ screen Specify screen, or Default Screen (does nothing if no default exists) Inferred
Order_Details

Collection Property Methods

addAndEditNew Collection Property Method Navigate to AddEdit screen for new entity in collection Specify screen Inferred
editSelected Collection Property Method Navigate to AddEdit screen for selected entity in collection Specify screen Inferred
showSearch Collection Property Method Open search bar for collection (be sure to mark the entity as searchable, otherwise the search bar may be hidden.) N/A N/A
viewSelected Collection Property Method Navigate to View screen for selected entity in collection Specify screen, or Default Screen (does nothing if no default exists) Inferred
createOrUploadDocument*
*Only available to document libraries
Collection Property Method Create or upload a document to document library Inferred Inferred
Navigation

Screen Methods (to navigate within current screen) and Application Methods (to navigate between screens)

showTab Screen Method Navigate to tab defined on current screen Specify tab Inferred
showPopup Screen Method Navigate to popup defined on current screen Specify popup N/A
showBrowseProducts Application Method Navigate to BrowseProducts screen Inferred N/A
showViewOrder_Detail Application Method Navigate to ViewOrder_Detail screen Inferred Specify scalar property
showViewProduct Application Method Navigate to ViewProduct screen Inferred Specify scalar property

Once you select a method, you may be required to fill in some additional information specifying the screen you’d like to navigate to and/or a property parameter.

3. Specify the screen you’d like to “Navigate To”

First, you’ll be prompted to select which screen/tab/popup you would like to “Navigate To” because there may be multiple applicable screens. No need to fill it in for the show<Screen> application methods because that information is inferred.

Edit-ItemTap-Action-viewSelected-Method 

In this case, we’ve only defined a single View screen for Order_Detail, so that’s the only screen we’ll show you.

4. Specify a property parameter

Lastly, you may be prompted to specify the property you’d like to use as a parameter for the screen.

This information is inferred for all but the application methods that accept parameters (i.e. those associated with AddEdit and View screens.) As an example, open the ViewOrder_Detail screen and add a reference to the corresponding Product.

ViewOrderDetail-Designtime

Open the tap action dialog for the Product property you just added.

Product-Tap-Action

To make this property navigate to the View screen for the associated Product, edit the tap action to use the showViewProduct method. Enter “Order_Detail” as the property parameter to access the Order_Detail currently associated with that screen, and “OrderDetail.Product” to access the associated Product property.

ItemTap-Action-showViewProduct

The process is a little more elaborate when navigating from a collection to a method that expects a scalar property parameter. Let’s say you wanted to use the showViewOrder_Detail method to navigate from the Order_Details collection in the ViewProduct Screen to the view screen for the Order_Detail item that was tapped (instead of using the preferred viewSelected method.) You could open up the ItemTap Action for the Order_Details Tile List, select the “showViewOrder_Detail” application method, and set the scalar property parameter (Order_Detail) to “Order_Details.selectedItem” to reference the selected item in the Order_Details collection.

Edit-ItemTap-Action-showViewOrder_Detail-Method

As expected, you can continue chaining properties together. To specify the Product associated with the selected Order_Detail, use “Order_Details.selectedItem.Product".

Order_Details-ItemTap-showViewProduct-Method 

And to specify a Category associated with that Product… you guessed it! “Order_Details.selectedItem.Product.Category”.

Of course, a more elegant solution in this particular case would be to specify “Product.Category” as the property parameter, but you get the gist.

Wrapping Up

Well that’s all for now. Questions, comments, complaints? We’d love to hear from you, so click your heels together three times and say ‘There’s no place like LightSwitch’ to leave a comment below or visit our forums. Happy item-tapping!

– Sara Itani, Software Developer, Cloud Business Apps