Beginning LightSwitch in VS 2013 Part 3: Screen Templates, Which One Do I Choose?

Article
11/04/2013

NOTE: This is the Visual Studio 2013 update of the popular Beginning LightSwitch article series. For previous versions see:

Welcome to Part 3 of the Beginning LightSwitch in Visual Studio 2013 series! In part 1 and part 2 we learned about entities and relationships in LightSwitch and how to use the Data Designer to define them. If you missed them:

Beginning LightSwitch in VS 2013 Part 1: What’s in a Table? Describing Your Data
Beginning LightSwitch in VS 2013 Part 2: Feel the Love - Defining Data Relationships

In this post I want to talk about screens. Screens are a common term in everyday life usually denoting a television or computer screen – the shiny thing we look at to interact with the device. In LightSwitch screens present data to the user and form the application’s user interface (UI).

In a business application screens allow users to search for, edit, insert and delete data in the backend data sources. LightSwitch makes the creation of screens really simple by providing templates you can choose from. You can then use them as is, or customize them further for your needs. Once you have some entities defined (like you learned in the previous posts) then you are ready to create screens.

Screens in the LightSwitch HTML client are optimized for touch-centric devices like tablets and mobile phones, however, you can also use any modern (HTML5-capable) browser to interact with the application. LightSwitch does the work for you to adapt the screens to fit different form factors using responsive design principles. For instance, as the screen gets smaller, items laid out in multiple columns will collapse into a single column and margins, spacing, titles and icons will decrease in size.

This means that when you create a LightSwitch application, it will automatically scale to the sizes of your user’s devices -- be that desktop, tablet, or phone form factors -- so you can write one application for many types of devices and operating systems.

For more information on how LightSwitch uses responsive design see: Designing for Multiple Form Factors

Choosing a Screen Template

You can add a screen to your project by clicking the “+ Screen…” button at the top of the Data Designer in the client perspective or by right-clicking on the Screens folder in the Solution Explorer and selecting “Add Screen…”

When you do this the “Add New Screen” dialog appears which asks you to select a screen template as well as the data you want to display on the screen. There are three screen templates available for the HTML client; the Browse Data Screen, View Details Screen, and Add/Edit Details Screen. Depending on the screen template you choose, your options in the “Screen Data” section on the right changes.

When you select the Screen Data drop down, you select the entity you want to use on the screen. On any screen template you choose, the controls are created in a similar way by looking at the entity definition. For instance, the labels inherit from the name of your fields. Also by default, screens use controls that match the underlying data types. So for instance, an editable String property is represented by a Text Box control, a Boolean becomes a Flip Switch control, a Web Address type gets the Web Address control, etc. This is why it’s important to model your data correctly before creating screens. Although you can customize most of these things on a screen-by-screen basis, LightSwitch reads the settings in your data model to create smart defaults, speeding up the time it takes to create the application.

Let’s walk through this list of screen templates and some guidelines on why you would choose them.

Browse Data Screen

You use the Browse Data Screen when you want to see a list of all the records in a table on one screen. By default, the screen contains a simple list that asynchronously loads pages of data as the user scrolls down. Like all screens that work with multiple data rows, the query will return 45 rows of data per page by default (you can change this on the screen properties). Lists of data can also be represented by a Tile List or a Table which are better for displaying multiple columns of data for each record.

Typically you will use a Browse Data screen as the “Home” screen for your application -- the first screen that is displayed when a user navigates to your app. You can easily hook up a “Tap” event so that when users touch (or click) an item in the list, you can navigate to a detail screen. If you choose the Browse Data screen template and run your app (F5) immediately, you will see a simple list. A list is a great control for smaller form factors (like a phone) or when you are only displaying one row of text and you want it to take up the width of the screen. By default a list displays the summary property that you define on the entity as we discussed in Part 1. By default, the summary property is the first string field in the table but you can change this in the Data Designer.

If you want to display multiple fields, consider a Tile List or Table control.

You can also add buttons in the command bar (or anywhere else on the screen) using pre-defined actions like add, edit and view that will take you to the appropriate screen templates for those actions (which we will discuss next).

View Details Screen

The View Details Screen allows you to view a single row of data from a table and optionally display any related data. Use a View Details Screen when you want to display all the details of an entity. By default LightSwitch will read the order of fields in your entity and split them into two columns, selecting the proper view controls based on the property types. You can also choose to include related child data on a View Details screen. By default, each set of related data will show up in a separate Tab on the screen which works well for small form factors or when you have a lot of related data to display.

However, if you are working with smaller sets of data or your users typically have larger screens, then you can place all the data on a single page by dragging the lists from the child tabs into the Details tab.

Add/Edit Details Screen

The Add/Edit Details Screen allows you to add or edit a single row of data from a table and optionally display any related data. The Add/Edit Details Screen template is very similar to the View Screen, except that by default, the fields are editable. This screen can be used for both editing current records as well as adding new ones.

Use an Add/Edit Details Screen when you want to add or edit details of an entity. By default, LightSwitch will read the order of fields in your entity and split them into two columns, selecting the proper edit controls based on the property types. You can also choose to include related child data on an Add/Edit Details screen just like a View Details Screen and each set of related data will show up in a separate Tab. However, you may want to design your screen workflow to make targeted edits to smaller sets of data at a time, especially if you are targeting small input devices. So even though you can edit related data on these screens, you may decide it’s better to present the View Screen to users and add buttons to edit each section individually.

The main difference between a View Details Screen and an Add/Edit Details Screen is that the latter is editable and will have Save and Cancel icons on the screen. By default, this screen is also shown as a dialog, but you can take up the full width of the browser by unchecking “Show As Dialog” in the appearance section of the properties window on the Screen Designer.

At first glance, three screen templates may look like a small set to work with. Remember however, that these are just starting points that you can fully customize. You have a lot of flexibility with laying out data (and related data) on screens. How much data and how you display it is totally up to you.

For design considerations, particularly with related sets of data, see: Master-Detail Screens with the LightSwitch HTML Client

Adding Screens to the Address Book Application

Now that you understand what each screen template gives you, let’s create some screens for the Address Book application we’ve been building in this series. At the end of the previous post we used the Browse Data and Add\Edit Details screen so that we could quickly test our data model.

However, if we wanted to manage thousands of contacts for a business and allow multiple users accessing that data, it’s probably better to put users into a workflow where they first search for a contact and then can either edit one at a time or add a new one if they don’t find the contact they were looking for. It’s always good to create a simple flowchart of how the application should work:

First the user searches for a contact using the Browse Data Screen and if found then open the View Details screen which will display all the related data. This screen will also let them make targeted edits to any of the contact details or related data. Once the user saves, the View Details screen is simply redisplayed until they navigate back to the Browse Screen. If the user does not find the contact they were looking for, they can open the Add Contact screen which allows them to enter just the contact entity data. When they Save, the Contact View Details screen opens and they can finish entering any related data if they need.

So we need six screens for our Address Book application; Browse Data Screen, View Details Screen, and four Add/Edit Screens each for the four entities in our application (Contact, EmailAddress, PhoneNumber, Address). The first screen you create becomes your Home screen so we’ll want to create the Browse Data Screen first. (If you’ve been following along, first delete the two test screens we created in the previous posts).

So first create the Browse Contact Screen by right-clicking on the Solution Explorer and selecting “Add Screen..” to open the Add New Screen dialog. Select the Browse Data Screen template and then select the Contacts Screen Data and click OK.

Next we’ll add search functionality to the Browse Contacts screen by modifying the query. We’ll talk about queries in the next post in more detail, for now, let’s just make a quick modification to the screen query so that a user can optionally search for a contact instead of having to scroll through the list.

In the Screen Designer click on the “Edit Query” on the view model on the left hand side. This contains all our properties, queries and methods on the screen.

This will open the Query Designer where you can provide a filter and a sort. Let’s allow the user to do a simple search on the contact name. We’ll search the LastName and the FirstName for matches. So add a Where clause, select the LastName property, contains, select Parameter [@], then select Add New… to create a new parameter.

Name the parameter “FindContact” and in the properties window check “Is Optional”. Then add another where clause (Or) , and choose the FirstName property. Let’s also provide a sort by FirstName then LastName. Here’s what the query should look like:

Click the “Back to BrowseContacts” in the upper left to get back to the screen designer. Now we see the FindContact screen property in our view model connected to the query parameter. We can simply drag the screen property above our list and set the control to a Textbox. In the properties set the Placeholder to “Find Contact” and the Label Position to “None”. This will help conserve space on the screen.

Let’s also change the Summary control under our list to a Columns Layout and under that, display the FirstName and LastName. This is what the Screen Designer should look like now.

Next let’s add a button to the command bar so we can add new a contact if the user doesn’t find the one they are looking for. Select the Command Bar, click +Add to add a new button and select the existing method, addAndEditNew. LightSwitch knows we need a new screen for this so Navigate To: (New Screen…) is selected. Click OK.

This opens the Add New Screen dialog again with the Add/Edit Details screen template automatically selected for our Contact. Click OK.

Flip back to the Browse Contacts screen and select the Add Contact button and in the properties window set the Icon to “Add”. You can choose from about 30 different built-in icons (and you can change them via CSS - more on that in a later post).

Next let’s add the View Details Screen for the contact. This will open when the user Taps (or clicks) on a contact in the list. Select the list and in the properties window click the Tap action link. Then select an existing method, viewSelected. Again, LightSwitch knows we need a new screen for this so Navigate To: (New Screen…) is selected. Click OK.

This time, select all the related data to include then click OK.

Now we can repeat the techniques we learned creating buttons and defining tap actions to create the three remaining screens in order to allow the user to add or edit the rest of our child entities. On the View Contact screen first select the Command Bar on the Details tab and add a button that allows us to edit the Contact Details. We can reuse the Add/Edit Contact screen we created earlier for adding new contacts.

Notice now when we select an existing method, we can see all the pre-defined actions for all of the queries on our screen.

LightSwitch knows we have a screen that can edit contacts already, so this will be selected automatically. Click OK. Then set the Icon of the Edit Contact button in the properties window to “Edit”.

(By the way, you may notice some fields are now appearing on the View Contact screen that we didn’t explicitly add in the Data Designer. By default, LightSwitch will add row-level Created/Modified & CreatedBy/ModifiedBy fields to new tables automatically so you can track when and who added or last edited a record later. You can change this setting on an entity in the Data Designer under the server perspective.)

I mentioned earlier that by default LightSwitch will lay out related children into separate tabs as you can see in the above screen shot. This is a good choice for smaller form factors or when you have potentially a lot of data in those child sets. Because it would be rare for a Contact to have more than a handful of Email Addresses, Phone Numbers or physical Addresses, let’s drag all the Lists into the Details tab and then delete the other tabs. I also changed the Lists to Tile Lists and have selected the specific fields I want to display.

Now that the lists are all on one tab, we’ll want to distinguish them by adding a header for each. Select the list and in the properties window check “Show Header” in the appearance section.

Now all we need to do is add the final Add/Edit screens for the child lists. Select the Tile List and set the Tap action to editSelected for each of the lists. LightSwitch will see that we need new screens for these so click OK through the dialogs.

Repeat this three times for each of the Tile Lists, picking the associated editSelected method for each.

On these screens we can remove the parent Contact picker that LightSwitch will put on the screen. This would be needed if we weren’t coming from a current Contact screen.

Finally add three “Add” buttons to the Command Bar for each of the children so a user can add records to each list. LightSwitch will suggest we reuse the Add/Edit screens we have which is exactly what we want.

You may be wondering at this point why the screen designer isn’t a typical WYSIWYG designer. This is because LightSwitch has two client options -- HTML and Silverlight -- and this allows us to keep the design experience similar. (If you want to learn how to build apps with the rich Silverlight client see the 2012 series).

However, there is a cool trick if you do want to actually see the affects of your changes. You can modify any client-side screen layout or JavaScript code while the application is running! Just make your modifications, save all of your files, then refresh your browser. For details on this handy screen development feature see: Speed up LightSwitch Development with “Edit & Refresh”

Customizing the Screen Workflow with JavaScript

When we designed our screen workflow I mentioned that after a new contact is created, we should navigate to the View Contact screen immediately so that a user can enter the rest of the contact details. Right now, the way it works is the Browse Contact screen will be shown after a new Contact is saved. This is because, by default, LightSwitch will simply navigate the user back to the screen they came from when they save. This works great for all our other Add screens because we execute them from the View Contact screen. However, our Add Contact button is on the Browse Contact screen.

All this means is we have to write a little bit of JavaScript code. On the Browse Contact Screen, select the Add Contact button and select “Edit Action”.

Then change the action to “Write my own method:” and click OK.

Right-click on the button again and select “Edit Execute Code”. This will navigate you to the code editor. Now write the following JavaScript code:

 myapp.showAddEditContact(null, {
    beforeShown: function (addEditScreen) {
        // Create a new contact here.
        var newContact = new myapp.Contact();
        addEditScreen.Contact = newContact;
    },
    afterClosed: function (addEditScreen, navigationAction) {
        // If the user commits the change, show the View screen
        if (navigationAction === msls.NavigateBackAction.commit) {
            var newContact = addEditScreen.Contact;
            myapp.showViewContact(newContact);
        }
    }
})

LightSwitch has a powerful client runtime that lets you do all sorts of things. We’ll talk more about customizing our applications with JavaScript and CSS in a later post. For now, take a look at how to program some of the common tasks here (which is where I got the above code :-)): How to: Modify an HTML Screen by Using Code

Run it!

Now that we have all our screens defined hit F5 to build and run the application and let’s see what we get. You will notice that the Browse Contact screen opens which allows us to find a contact. I only have a couple rows of test data in here but if I had hundreds of contacts, LightSwitch would load only 45 rows at a time, loading more only when we scrolled to the bottom of the list.

If you click on the name of a contact in the list it will open the View Contact screen which allows us to edit all the contact information. If we click on the Add Contact in the Command Bar, it will open the Add/Edit Contact screen and when we save, it will navigate immediately to our View Contact screen.

From here, the user can interact with all the data. Tapping the tiles will edit the related data, tapping the buttons in the Command Bar will perform the associated action. If the user taps a phone number or email link, the phone will dial or a new email will open.

Wrap Up

As you can see the built-in screen templates provide a lot of functionality for you. We now have a fully functional HTML5 business application and we wrote minimal code. That’s the power of LightSwitch. It handles all the boring plumbing code for you but still provides a rich API on both the client (JavaScript) and the server (.NET).

Next post we’ll look deeper at queries and how to design them in order to filter and sort data on our screens exactly how we want. Until next time!

Enjoy!

Read the next article –> Part 4: Too much information! Sorting and Filtering Data with Queries

Comments

Anonymous
November 04, 2013
Thanks for this!!! It's Awesome...
Anonymous
November 05, 2013
Great article again! I'm just planning a quite complex WF 4.5 based system w. tracking,perseistence etc, and I wondering if I should use my WF somehow within a lightswitch 2k13 project. I couldn't find any example about this possibility on the web only some notes, could you show me a small real example of such a solution if possible and exists? On offical forum there is nothing. Thanks.
Anonymous
November 21, 2013
Merci pour ce tutoriel. Vous faites un excellent travail.
Anonymous
November 21, 2013
Your demo is really great ! I'm building a time tracker for an accounting firm as a student project. Lightswitch is perfect for this kind of stuff ! Thank you for the demo. I'm looking forward to the next article !
Anonymous
November 24, 2013
I'm making my way through this, does anyone know how to change the property of the drop down to allow me to type in the first few characters and it drill down to that data. So, for example when choosing a dropdown of customers, I want to be able to type in "CA" and it go down to "Cabonera" if that's the first customer beginning with CA.
Anonymous
November 28, 2013
The comment has been removed
Anonymous
July 08, 2014
I have replicated the same case as Kevin J
Anonymous
July 08, 2014
I solved it by adding ";" in the end
Anonymous
August 11, 2014
Hello Betty I admire your enthusiasm and it's contagious!! Thank you for solving of this problem
Anonymous
August 18, 2014
Hi Beth, hi everybody, @Beth Thanks a lot for the sample, fun to work with it :-). I've had the same problem as Kevin and Oleh, thanks for posting the solution. Apart from that I've gotten another problem, which I am not able to solve. My search field FindContact does not display the Placeholder " Find Contact" it's empty, dunno why? Would be nice to get a hint, Thx J
Anonymous
December 16, 2014
I love building business apps using mouse clicking. But is there a way to easily delete record? Thanks in advance.
Anonymous
January 08, 2015
The comment has been removed
Anonymous
January 08, 2015
Using HTML client in above question.

Share via