Note: This article has been updated for Beta 2 on 3/17/2011
Summary Properties in LightSwitch are properties on your entities (tables) that “describe” them (kind of like the .ToString() method on objects in .NET). A summary property is used by LightSwitch to determine what to display when a row of data is represented on a screen. Therefore, it’s important to get them right so that your data is represented to users in a clear way. In this post I’ll explain how to specify these properties on entities as well as how they work in LightSwitch applications.
Specifying Summary Properties on Entities (Tables)
Regardless of whether you are creating new database tables or attaching to an existing data source, summary properties are used to describe your entities as you model them in the designer. By default, LightSwitch will choose the first string property on your entity as the summary property. For instance, say we have a Customer entity with the following properties pictured below. If you select the Customer entity itself (by clicking on the name of it) you will see that the summary property is automatically set to LastName in the properties window. This is because the LastName property is the first property listed as type string.
In most cases this is the correct behavior you will want, however, for a Customer it makes more sense to display their full name instead. We can easily do this using a computed property. To add one, click on the “Computed Property” button at the top of the designer. This sets the Is Computed property in the properties window for you. Name the property FullName and then click on the “Edit Method” link in the properties window. This method is where you return the value of the computed field.
Computed fields are not stored in the underlying database, they are computed on the entity and only live in the data model. For FullName, I will return “LastName, FirstName” by writing the following code (in bold).
Public Class Customer Private Sub FullName_Compute(ByRef result As String) ' Set result to the desired field value result = Me.LastName + ", " + Me.FirstName End Sub End Class
To set the FullName as the summary property, go back and select the entity’s name and you will now see FullName in the dropdown on the properties window as an available choice to use as the entity’s summary property.
Summary Properties in Action
Summary properties are displayed anytime you use the Summary control on a screen or when LightSwitch generates a layout for you that needs to display a description of the entity. For instance, to see this summary property in action create a search screen for the customer. Click on the “Screen…” button at the top of the designer, select the Search Screen template and select Customer as the screen data:
(Note, if you don’t have any records in your development database then also add a New Data Screen to enter some data first).Take a look at the Full Name label control in the screen designer of the search screen. Because this is a summary property it will display as a hyperlink to allow the user to open the specific record as indicated by the “Show as Link” in the Appearance section of the properties window. You can also choose which screen it should open. By default, the default edit screen is opened.
Hit F5 to run the application and open the customer search screen. Notice that the Full Name field is displaying as a clickable hyperlink.
If we click it, then then LightSwitch will generate an edit screen for us to access the record. Notice that the titleof the generated Edit screen also displays the summary property:
Summary properties also show up in child grids and modal window pickers as well.
More Examples of Summary Properties
Summary properties are not required to be strings, they just have to be able to be represented as strings. For instance, maybe you have an entity that captures date ranges or some item that would be better represented as a date. For our example say we have an Appointment entity and we’ve set a relation where a Customer can have many Appointments. The Appointment table has properties Subject, StartTime, EndTime and some Notes. We can select any of these properties as summary fields. You can even mix+match them by creating a computed property just like before, you just need to make sure the properties can be converted to a string.
Private Sub Summary_Compute(ByRef result As String) ' Set result to the desired field value result = Me.StartTime + ": " + Me.Subject End Sub
Another thing that you can do is show data from a related entity. For instance if you have an OrderDetail line item that has a reference lookup value to a Product table, you may want to display the Product Name on the OrderDetail. Create a computed property and then just walk the association to get the property you want on the related entity. Just make sure you perform a null check on the related property first:
Private Sub Summary_Compute(ByRef result As String) ' Set result to the desired field value If Me.Product Is Nothing Then result = "<New Product> - Quantity: " + Me.Quantity Else result = Me.Product.Name + " - Quantity: " + Me.Quantity End If End Sub
Keep in mind that summary properties are meant to be displayed throughout the application and should not be too lengthy or complicated. Keeping them down to 50 characters or less will make the application look less cluttered.