Walkthrough: Creating a LightSwitch Client for Mobile Users

Article
04/28/2015

By using LightSwitch, you can create an HTML client in which mobile users can view, add, and update data from remote locations by using modern, touch-oriented devices such as phones and tablets. In this walkthrough, you'll create a client for a fictional moving company, Contoso Moving, so that its customer-service staff can more easily estimate how many people, trucks, and boxes each job will require.

At Contoso, schedulers spend most of their time in the office, talking to prospective customers in person or on the phone and arranging follow up visits. These workers use a rich desktop client that's based on Silverlight and that better supports heavy data entry with the keyboard and mouse. In contrast, the planning specialists travel all day, making follow up visits in various locations and recording information such as the size, contents, and entry requirements of each room. These mobile users need a client that not only shows them information about each follow up visit from the schedulers but also supports entering specific types of data, taking pictures, and alerting the move team about parking restrictions or other details.

The desktop client for the schedulers has already been built. You’ll build the mobile client that the planning specialists use to track the appointments that the schedulers arrange and to enter details about each move.

Prerequisites

Download the ContosoMoving sample application.

Getting Started

Before you build the mobile client, you will create some sample data for the desktop client, which you downloaded.

To create sample data

On the menu bar, choose File, Open, Project/Solution.
Locate the ContosoMoving.sln file that you downloaded, and then open it.
On the menu bar, choose Debug, Start Debugging.
In the running client, on the menu bar, choose Sample Data, Create Sample Data.
On the toolbar in the Create Sample Data screen, choose the Add All Sample Data button.

Sample data is created for the State, Employee, Customer, and Appointment entities.
On the toolbar, choose the Save button.
On the menu bar, choose Home.
On the toolbar, choose the Refresh button.

A list of upcoming appointments for all employees appears, and you can explore the other screens in the desktop client.

Add a mobile client

Next you will add an HTML client project to the existing solution.

To add an HTML client project

In Solution Explorer, choose the ContosoMoving node.
On the menu bar, choose Project, Add Client.
In the Add Client dialog box, choose HTML Client, name it MobileClient, and then choose the OK button.

A MobileClient project node is added to Solution Explorer.

Next you will create a home screen and a details screen, define the navigation between the screens, and create a modal dialog box. Mobile clients use a different navigation model than desktop clients. Typically, only one screen is visible at a time in a mobile client, and changes are committed when you move from one screen to another.

To create a home screen

In Solution Explorer, choose the MobileClient node.
On the menu bar, choose Project, Add Screen.
In the Add New Screen dialog box, choose the Browse Data Screen template.
In the Screen Name text box, enter Home.
In the Screen Data list, choose UpcomingAppointments, and then choose the OK button.

To customize the home screen

In the screen designer, choose the Appointment node, and then choose Rows Layout in the drop-down list.
Under the Rows Layout | Appointment node, delete all nodes except for Start Date and Customer.
On the menu bar, choose Start Debugging.

The mobile client appears in the browser.

At this point, the screen displays only the appointments. Next you’ll add a details screen so that appointment details appear when a user taps an appointment.

To create a details screen

In the screen designer, choose the Upcoming Appointments node.
In the Properties window, choose the Item Tap : None link.
In the Edit ItemTap action dialog box, choose the Choose an existing method option button, and then choose UpcomingAppointments.ViewSelected in the list.
In the Navigate To list, choose (New Screen), and then choose the OK button.

The Add New Screen dialog box appears.
In the Add New Screen dialog box, choose the View Details Screen template.
In the Screen Name text box, enter ViewAppointment.
In the Screen Data list, choose Appointment.
Select the Appointment Details, Appointment Photos, and Appointment Rooms check boxes, and then choose the OK button.

In the screen designer, a Tabs layout is created, and the different types of data are organized by tabs.
On the menu bar, choose Start Debugging to run the mobile client.
Tap an appointment to display the View Appointment screen.
Resize the browser window, and notice how the layout changes between two columns and a single column.

To customize the details screen

In Solution Explorer, open the ViewAppointment screen.
In the screen designer, choose the Rows Layout | Details node.
Delete the Start Date, End Date, Notes, Move Type, Employee, and Customer nodes.
Move the State node so that it appears under the City node.
Choose the Rows Layout | right node, expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Customer.Phone, and then choose the OK button.
Expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Customer.Email, and then choose the OK button.

In Solution Explorer, open the ViewAppointment screen.
In the screen designer, open the shortcut menu for the Command Bar node of the Details tab, and then choose Add Button.
In the Add Button dialog box, choose the Choose an existing method option button, and then choose Appointment.edit in the list.
In the Navigate To list, choose (New Screen), and then choose the OK button.

The Add New Screen dialog box appears.
In the Screen Name text box, enter EditAppointment, and then choose the OK button.

In the Properties window, the Show As Dialog check box is selected, which means that the screen will appear as a modal dialog box.
In the screen designer, delete the Columns Layout | columns node.
Expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Appointment.Customer.FirstName, and then choose the OK button.
Expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Appointment.Customer.LastName, and then choose the OK button.
Expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Appointment.Customer.Phone, and then choose the OK button.
Expand the Add node, and then choose Other Screen Data.

The Add Screen Data dialog box appears.
In the Specify the screen data to add text box, enter Appointment.Customer.Email, and then choose the OK button.
In the left-hand pane, drag Street, City, State, and PostalCode under the Email node.

Note

Instead of dragging, you could also add the Street, StreetLine2, City, State, and PostalCode fields by following the same steps as the FirstName and LastName fields.

To show the dialog box

In Solution Explorer, open the ViewAppointment screen.
In the screen designer, choose the Edit Appointment node.
In the Properties window, expand the Icon, list and then choose Edit.
On the menu bar, choose Debug, Start Debugging to run the mobile client.
In the running client, tap an appointment to open a View Appointment screen.
Tap the Edit Appointment button to display the dialog box.

OK and Cancel buttons are included automatically.

Customize the User Interface

You can customize the user interface of your client not only by changing settings in the screen designer but also by adding custom controls and writing JavaScript code.

To apply custom formatting by using JavaScript libraries

In Solution Explorer, open the Home screen.
In the screen designer, choose the Rows Layout | Appointment node, and then choose Custom Control in the list.
In the Write Code list, choose the RowTemplate_render method.

In the code editor, add the following code for the RowTemplate_render function:

myapp.Home.RowTemplate_render = function (element, contentItem) {
    var itemTemplate = $("<div> </div>");
    var title = $("<h3>" + moment(contentItem.value.StartDate).format("ddd, MMM Do, h:mm") + "-" + moment(contentItem.value.EndDate).format("h:mma") + "</h3>");
    var subTitle = $("<span>" + contentItem.value.Customer.FirstName + " " + contentItem.value.Customer.LastName + " - " + contentItem.value.Customer.Phone + "</span>");
    title.appendTo($(itemTemplate));
    subTitle.appendTo($(itemTemplate));
    itemTemplate.appendTo($(element));
};

This JavaScript code uses the contentItem.value member variable to determine what to display and the format method to define the formatting.

In Solution Explorer, open the shortcut menu for the MobileClient node, and then choose Manage NuGet Packages.
In the Manage NuGet Packages dialog box, choose the Online node.
In the Search Online text box, enter moment.js.
Choose the Install button to install the Moment.js library, and then choose the Close button.
In Solution Explorer, expand the MobileClient node, and then open the default.htm file.
In the code editor, add the following script tag after the last </script> tag:
```
<script type="text/javascript" src="Scripts/moment.js" charset="utf-8"></script>
```
This tag adds a reference to the moment.js library.
On the menu bar, choose Debug, Start Debugging to run the client.

The appointment is formatted, and the time and the phone number are added.

To change the layout to a tiled list

In Solution Explorer, open the Home screen.
In the screen designer, choose the List | Upcoming Appointments node, and then choose Tile List in the list.
On the menu bar, choose Debug, Start Debugging to run the client.

The home screen displays upcoming appointments in a tile-based layout. Change the width of the browser window to demonstrate how the layout of the tiles dynamically adjusts to make good use of available horizontal space. This demonstration shows how the list layout could change based on the orientation and screen size of a mobile device.

To add a dynamic screen title

In Solution Explorer, open the ViewAppointment screen.
In the screen designer, choose the Rows Layout | Details node.
In the Write Code list, choose Details_postRender.

In the code editor, add the following JavaScript code:

myapp.ViewAppointmentDetail.Details_postRender = function (element, contentItem) {
    contentItem.dataBind("value.Appointment.Customer.FirstName", function () {
        formatAppointmentScreenTitle(contentItem);
    });

    contentItem.dataBind("value.Appointment.Customer.LastName", function () {
        formatAppointmentScreenTitle(contentItem);
    });

    function formatAppointmentScreenTitle(contentItem) {
        contentItem.screen.details.displayName = contentItem.value.Appointment.Customer.FirstName + " " +
        contentItem.value.Appointment.Customer.LastName + " " +
        moment(contentItem.value.Appointment.StartDate).format("h:mma") + " - " +
        moment(contentItem.value.Appointment.EndDate).format("h:mma");
    };
};

On the menu bar, choose Debug, Start Debugging to run the client.

The appointment-detail screens show the customer’s name and the start and end times for the appointment.

Add a Custom Control to Upload Photos

The appointment details screen has an Appointment Photos tab so that a planning specialist for Contoso Moving can take pictures of a customer’s site to estimate the job more accurately. To enable this task, you will add a custom control to the client.

To add a custom control

In Solution Explorer, open the shortcut menu for the Scripts node, choose Add, and then choose Existing Item.
In the Add Existing Item dialog box, navigate to the ContosoMoving folder, and then open the Sample Resources folder.
Choose the image_uploader-base64-file-encoder and image-uploader files, and then choose the Add button.
Open the default.htm file, and then, in the code editor, add the following reference to image-uploader.js at the end of the script references block:
```
<script type="text/javascript" src="Scripts/image-uploader.js" charset="utf-8"></script>
```
In Solution Explorer, open the ViewAppointment screen.
In the screen designer, choose the List | Photos node, and then choose Tile List in the list.
In the Properties window, open the Height property list, and then choose Stretch to Container.
In the Min text box, enter 150.
In the screen designer, open the shortcut menu for the Photos tab Command Bar node, and then choose Add Button.
In the Add Button dialog box, choose the Choose an existing method option button, choose Photos.addEditNew in the list, and then choose the OK button.

The Add New Screen dialog box appears.
In the Screen Name text box, enter UploadPhoto, and then choose the OK button.
In the screen designer, delete the Rows Layout | right node.
Choose the Caption node, and then change the control type to Text Area.
Choose the Picture node, and then change the control type to Custom Control.
In the Properties window, choose the Edit Render Code hyperlink.
In the code editor, add the following code to the Picture1_render function:
```
createImageUploader(element, contentItem, "max-width: 300px; max-height: 300px");
```
This code initializes the ImageUploader custom control when the screen is rendered.
In Solution Explorer, open the ViewAppointment screen.
In the screen designer, choose the Add Photo button node, and then change the Icon property to Add Picture.
On the menu bar, choose Debug, Start Debugging to run the client.
In the running client, tap an appointment.
On the appointment detail screen, tap the Photos tab.
Tap the Add Photo button to open the Image Uploader dialog box.

Map the Customer’s Address

The planning specialist must also be able to find the customer’s site, so next you will add mapping functionality by using a Bing map control.

To add a map control

In Solution Explorer, open the shortcut menu for the Scripts node, choose Add, and then choose Existing Item.
In the Add Existing Item dialog box, navigate to the ContosoMoving folder, and then open the Sample Resources folder.
Choose the lightswitch.bing-maps.js file, and then choose the Add button.

Open the default.htm file and then, in the code editor, add a reference at the start of the script references block:

<script type="text/javascript" charset="utf-8" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

At the end of the script references block, add a reference to the JavaScript file:

<script type="text/javascript" src="Scripts/lightswitch.bing-maps.js" charset="utf-8"></script>

In Solution Explorer, open the ViewAppointment screen.
In the screen designer, open the shortcut menu for the Tabs node, and then choose Add Tab.
In the Properties window, set the value of the Name property to Map.
Open the shortcut menu for the Rows Layout | Map node, and then choose Add Custom Control.

The Add Custom Control dialog box appears.
In the Specify the data for the new custom control text box, enter Appointment, and then choose the OK button.
In the Properties window, choose the Edit Render Code hyperlink.

In the code editor, add the following utility methods before the Appointment_render function:

function rebindMap(element, contentItem) {
    // Verify that we aren't updating the map continuously due to multiple bound values changing.
    var now = new Date();
    if (now.getTime() - mapLastUpdated.getTime() > 15) {
        setTimeout(function () {
            updateMap(element, contentItem);
            mapLastUpdated = new Date();
        }, 20);
    }
};

function updateMap(element, contentItem) {
    var mapDiv = $("#appointmentMap");
    // If we've previously created the map, make sure to clean up the div that contained it;
    // otherwise, the Bing map control fails to create properly.
    if (mapDiv.length > 0) {
        $(mapDiv).remove();
    }
    mapDiv = $("<div id='appointmentMap' class='msls-hauto msls-vauto' ></div>");

    $(mapDiv).appendTo($(element));
    mapControl = mapDiv.lightswitchBingMapsControl({
        street: contentItem.value.Street,
        city: contentItem.value.City,
        state: contentItem.value.State.Name,
        zipcode: contentItem.value.PostalCode,
        mapTypeId: Microsoft.Maps.MapTypeId.road,


        height: "400"
    });
};

Add the following code to the Appointment_render function:

updateMap(element, contentItem);
mapLastUpdated = new Date();
    contentItem.dataBind("value.Street", function () { rebindMap(element, contentItem); });
    contentItem.dataBind("value.City", function () { rebindMap(element, contentItem); });
    contentItem.dataBind("value.Zip", function () { rebindMap(element, contentItem); });
    contentItem.dataBind("value.PostalCode", function () { rebindMap(element, contentItem); });

This code binds the fields of the appointment to the map control when the screen is rendered.

On the menu bar, choose Debug, Start Debugging to run the client.
In the running client, tap an appointment.
On the appointment detail screen, tap the Map tab to display a map of the customer’s address.

Add Branding

Next you’ll change the title of the client to something more meaningful than MobileClient, and you’ll add a Contoso Moving corporate logo to personalize the client.

To change the title

In Solution Explorer, open the default.htm file, and then, in the code editor, replace the <title>MobileClient</title> element with the following code:
```
<title>Contoso Moving Mobile</title>
```

To add an icon

In Solution Explorer, expand the Content and Images nodes.
Delete the user-logo.png file.
Open the shortcut menu for the Images node, choose Add, and then choose Existing Item.
In the Add Existing Item dialog box, navigate to the ContosoMoving folder, and then open the Sample Resources folder.
Choose the user-logo.png file, and then choose the Add button.

Note

You can also customize the image that appears on the splash screen if you replace the user-splash-screen.png file.
On the menu bar, choose Debug, Start Debugging to run the client.

Note

You may need to clear your browser cache before the changes will appear.

Change the Theme

Cascading style sheets (CSS) to define the theme of a client. You can modify the default theme to change the appearance of your client, or you can replace that theme by changing the .css file. You will use a web tool, ThemeRoller, to create a.css file with a customized theme.

To switch between themes

In Solution Explorer, open the default.htm file, and then, in the code editor, replace “light” in the following two lines <link rel="stylesheet" type="text/css" href="Content/light-theme.css" />, <link rel="stylesheet" type="text/css" href="Content/msls-light.css" />with dark.
On the menu bar, choose Debug, Start Debugging to run the client.

To customize an existing theme

In your web browser, navigate to the ThemeRoller website.
On the ThemeRoller toolbar, choose the Import or upgrade button.

The Import Theme dialog box appears.
In Visual Studio, in Solution Explorer, choose File View from the list on the toolbar.
Expand the Content node, and then open the dark-theme.css file.
In the code editor, copy the entire contents of the file.
In ThemeRoller, paste the contents of the dark-theme.css file into the Import Theme dialog box, and then choose the Import button.
In the left pane, choose the Global tab, and then expand the Corner Radii node.
In the Group text box, enter 0.8em.
In the Button text box, enter 1.5em.

The UI elements in the right-hand pane now have rounded corners.
In the right-hand pane, drag a color from the color palette onto the background area of Swatch A.
Drag another color onto the Radio element.

All related elements also change color. When you point to an element, it changes to a complementary color, indicating the selection color.
On the ThemeRoller toolbar, choose the Download button.
In the Download Theme dialog box, name the theme my-theme, and then choose the Download Zip button.
Extract the contents of the compressed file to a local folder.
In Solution Explorer, open the shortcut menu for the Content node, choose Add, and then choose Existing Item.
In the Add Existing Item dialog box, navigate to the folder where you extracted the files, choose the my-theme.css file, and then choose the Add button.
Open the default.htm file, locate the line <link rel="stylesheet" type="text/css" href="Content/dark-theme.css" charset="utf-8" /> in the code editor, and then replace ”dark-theme” with my-theme.
On the menu bar, choose Debug, Start Debugging to run the client.

Next Steps

You now have a working mobile client application. To test it on a mobile device, publish the application to Internet Information Services (IIS) or Microsoft Azure.

Walkthrough: Creating a LightSwitch Client for Mobile Users

Prerequisites

Getting Started

To create sample data

Add a mobile client

To add an HTML client project

Create Screens and Define Navigation

To create a home screen

To customize the home screen

To create a details screen

To customize the details screen

To show the dialog box

Customize the User Interface

To apply custom formatting by using JavaScript libraries

To change the layout to a tiled list

To add a dynamic screen title

Add a Custom Control to Upload Photos

To add a custom control

Map the Customer’s Address

To add a map control

Add Branding

To change the title

To add an icon

Change the Theme

To switch between themes

To customize an existing theme

Next Steps

See Also

Other Resources

Additional resources

Walkthrough: Creating a LightSwitch Client for Mobile Users

Prerequisites

Getting Started

To create sample data

Add a mobile client

To add an HTML client project

Create Screens and Define Navigation

To create a home screen

To customize the home screen

To create a details screen

To customize the details screen

To create a modal dialog box

To show the dialog box

Customize the User Interface

To apply custom formatting by using JavaScript libraries

To change the layout to a tiled list

To add a dynamic screen title

Add a Custom Control to Upload Photos

To add a custom control

Map the Customer’s Address

To add a map control

Add Branding

To change the title

To add an icon

Change the Theme

To switch between themes

To customize an existing theme

Next Steps

See Also

Other Resources

Additional resources