Creating Screens with the LightSwitch HTML Client (Joe Binder)

Beth and I touched on a few of the new features of the upcoming HTML client for LightSwitch in our Channel 9 video chat last week, but I thought it’d be worthwhile to cover each topic in more detail. Today I’ll walk through the application user model and screen development, then follow-up with in-depth posts that cover writing code, theming, and the application architecture.

If you’ve seen some of the sneak-peeks at the HTML client in Jay Schmelzer’s TechEd session or our Channel 9 video, you may have noticed that the development experience for building HTML clients is pretty similar to the experience in Visual Studio LightSwitch 2011. We tried to keep the development process consistent with what you’ve seen and used in 2011. Where we did deviate, we did so largely in response to feedback and pain points we’ve heard in the forums and UserVoice. Keep that feedback coming: we very much appreciate and learn from the discussions that have cropped up the forums since the announcement.

The HTML Client Preview will be available for you to try out yourself soon. Keep an eye on this blog and the LightSwitch Developer Center for availability.

Getting started

Let’s get started by creating a new LightSwitch project. The first thing you’ll notice is that there are a few new project templates available in the LightSwitch 2012 HTML client preview.


The templates suffixed with (JS/VB) and (JS/C#) create a project with an HTML client and Visual Basic or C# middle-tier, respectively. The “LightSwitch Application (Visual Basic)” and “LightSwitch Application(C#)” templates create a project with a Silverlight client and middle-tier in the given language, just as they did in Visual Studio LightSwitch 2011. If you start with a Silverlight-based project, you can always add an HTML client later, and vice versa. Let’s create a new Silverlight-based project for this example.

The Solution Explorer has been restructured to more clearly delineate the server and client(s). Data sources, entities, and queries appear under the server node and screens appear under the client node(s).

Solution Explorer  - New project

The client with “(Startup)” listed in its name will be run when you press F5 to debug the application.

We’ll use the entity designer to quickly add some data entities to describe contact information. The entity designer in the HTML client preview is identical to the entity designer in Visual Studio 2012 RC.


With the entities and some basic Silverlight-based screens created, we can now add our HTML client by right-clicking the top-level “Contact Application” node in the Solution Explorer.



If we started with an HTML Client, we’d also see an option for adding a Silverlight client: the HTML client preview allows you to have zero or one Silverlight clients and zero or more HTML clients. The task-focused nature of mobile web clients means that it’s common to have multiple clients talking to the same middle-tier, each with their own specific workflow or user experience.

Once the new client is added, it is automatically marked as the startup client for the project.

Solution Explorer - Empty mobile client project

If you need to change the startup client, just right-click the client you want to debug and select “Set as startup client”.

Solution Explorer - New client added

Adding Screens

Screens/Pages for the HTML Client are added through the same “New Screen …” dialog that’s used for Silverlight clients. We have a pretty simplistic list of mobile-specific templates in the dialog, but we’d love to hear your feedback as we finalize the list. Screen templates are extensible, so we’re also excited to see some additions to this list from our partners in the near future.


The Browse Data Screen creates a full-screen list. This template is commonly used in conjunction with the View Details Screen, which shows a read-only view of a single record. We created separate templates for viewing and creating/editing detail records because mobile user interfaces are typically optimized for reading, and showing touch-oriented edit controls can impair the readability of the screen. Nonetheless, you can use the same details screen for reading and editing if you like; we just provide both options.

Once created, you’ll notice that we’re using the same screen designer that’s used for Silverlight—the data/view model is listed on the left and the screen layout/content is on the right.

Screen designer - Initial

Let’s add another detail screen that we can hook up to the list, such that the details screen is shown when the user taps on a list item.

NewScreenDialog - Details template

Note that when we include child collections on the details screen (e.g., “Contact Photos” and “Friends”) the template places each list in a separate tab. This division is done by default for two reasons:

1. The mobile device is unlikely to have enough screen real estate to show multiple lists on the same screen.

2. In general, having a single scrollable region in a mobile web application is easier to use because mobile browsers don’t show a scrollbar. Having multiple scrollable regions on the screen can make the swipe/scroll gesture ambiguous when the scrollbars aren’t visible.

With two screens in the client, we need to tell LightSwitch which screen should be used as the “Home” screen for the application. The home screen will be shown when the application is started, and the home button shown on other screens will link back to the home screen. We have some logic to guess what to use for the home screen, but you’re best bet is to set the home screen explicitly in Solution Explorer.

Set as home screen

Configuring application navigation

While JavaScript is a powerful and flexible language, we didn’t want to force developers to write JavaScript for tasks that could more easily be accomplished with the designer. Defining the application navigation and workflow is a great example of plumbing that you often have to express in code; but we chose to make this a code-free experience in the HTML Client, allowing you to link screens together with a few mouse clicks. Of course, you can still create a button and call the code if you need to do something more advanced—conditionally launch different screens, for example—but the UI-based experience covers most scenarios. Here’s how it works.

When you select a control in the screen designer, a list of “actions” will be displayed in the property sheet. These actions represent user gestures that can be performed on the control. Currently, “Tap” is the most common action, but controls may support things like “Swipe”, “Hold”, and so on in the future.

Tap action in property sheet

You can configure actions to execute methods that you’ve written or built-in methods associated with the view model. Click the link next to the action to configure it.

Edit Tap Action  - 1

The “Write my own method” option is not yet supported, so let’s explore the methods that LightSwitch provides.

Edit Tap Action  - 2

Notice that there are pre-defined methods for changing the selected tab/section on the screen, showing a dialog, navigating to the home screen, and launching any other screen defined in the application. Additionally, methods associated with anything on the screen view model will be shown here.

Since we want to show the contact detail screen, we’ll choose “ShowViewContactDetail”.

Edit Tap Action - 3

There are a few new options for showing a screen with the HTML client. The Save (default) option is analogous to the Silverlight client’s Application.ShowScreen() method, meaning that the screen will be launched with a new data context. The OK/Cancel option provides a modal experience, whereby users can make multiple edits to a record and choose to accept or cancel them as one edit; the changes are then added to the parent screen’s change set. The Back option is useful when you have a record with a lot of fields, and you want to divide the task of viewing or editing groups of fields into separate UI. There is descriptive text in the dialog to help describe the exact behavior you’ve chosen.

In this example, we want to use the Save option. Since we selected a details screen that accepts a Contact as a parameter, we also need to specify the parameter value, which is expressed as a binding to the Home screen’s view model—the selected item in the contact list.

Edit Tap Action - 4

The application navigation model

When the application is run, our list screen is shown and the details screen will be launched when a list item is tapped. The list does not include gestures for sorting and searching yet; you can use the query designer to configure the sort order in the meantime.

App running - 1

One important difference between the HTML and Silverlight client is readily apparent when we tap on an item: only one screen is visible at a given time. A built-in back gesture allows you to move back in your task flow. As mentioned earlier, the screen is divided into top-level tabs (Details, Photos, Friends) by default.

App running - 2

We can now customize this screen to include an “Edit” button. We’ll use the Add/Edit template to create the screen.

Add Screen - 2

Now we can just add a button to the existing ViewContactDetail screen that will show the ContactDetail screen.


In this example we’re using the OK/Cancel mode, which will cause the edit screen to be shown as a sub-screen of the contact detail screen.

ViewContactDetail - 1

Note that screens do not have Save gestures when they’re hosted as sub-screens.


Once we’ve made changes, we can click OK—the check icon—and see that the changes we’ve made have been added to the parent screen’s changeset.


Clicking Save will now save the changes we made in the sub-screen.

Dealing with multiple screen sizes

One of the most challenging aspects of building mobile web applications is optimizing for the screen size: the user may have anywhere from 480 to 1200+ pixels available for the width. We’ve just begun work to improve our layouts to be more adaptable to varying screen sizes, but there are a few hidden tricks you can use to work well in wide and narrow environments.

For example, our edit screen looks very silly in wide mode. (See above). What I’d really like to do is use some of that horizontal space if it’s available, but stretching the controls is a waste of space and distracting. Instead, we can use a columns layout and set a minimum width on each column.


(Note: be sure to uncheck “Stretch to container” for the width and height of each column also.)

Now when we run our application, the screen will use a two-column layout when we have at least 700 pixels—for example, on a tablet.


But if we are using a narrow device the columns will stack vertically and scroll if needed.


This area is ripe for some simplification, but I thought I’d pass along the tidbit in case you’re interested in seeing the app in a variety of screen sizes.

Next Up

This is an extremely simple application, but I hope it gives you a feel for the basic user and development models for the LightSwitch HTML Client. We’re putting together a detailed walkthrough of everything we’ve covered today that we’ll publish when the LightSwitch for Visual Studio 2012 HTML client preview becomes available. Keep an eye on this blog and the LightSwitch Developer Center for availability.

I intentionally left out any coding experiences in today’s post to illustrate the types of tasks you’ll be able to do without writing HTML, JavaScript or CSS. But we know a lot of you want to see some code examples and understand our application architecture—both are on tap for upcoming posts along with a theming overview.

As always, we’d love to hear from you over on the forums. Thanks for all of your feedback, suggestions, and encouragement!

Joe Binder, Senior Program Manager – LightSwitch Team