Building an HTML Client for a LightSwitch Solution in 5 Minutes

Building an HTML Client for a LightSwitch Solution in 5 Minutes

Rate This
  • Comments 12

If you haven’t heard, we released the HTML Client Preview 2 last week which adds the ability to create HTML5/JavaScript based clients to your LightSwitch solutions. I thought it would be a good exercise to add an HTML companion application to my Contoso Construction sample to demonstrate just how quickly you can build these clients.

Contoso Construction is a sample that uses LightSwitch extensions and slightly more advanced coding techniques in order to integrate with mail servers, automate Word and Excel, create map visualizations, provide advanced data filtering, and connect to OData sources. The Silverlight client is meant to run on the desktop and is used by the construction company to manage construction projects.

One of the features of the application is the ability to add photos of the construction site.


Right now, however, the way it works is someone on the site has to bring back the pictures to the office in order to upload them or the crew needs to carry around a laptop in order to run the rich desktop application. Instead, we want to be able to provide the ability to upload photos using any modern mobile device. So let’s see how we can build this companion client in minutes.

Add a Client

First thing we need to do is add a new mobile client to our current project. (You will need to first install the LightSwitch HTML Client Preview 2 in order to get this functionality. Keep in mind that this release is still in preview so make sure you don’t do this to any production applications – please use a copy ;)).

Right-click on the project node and select “Add Client…”



Then select HTML Client and name the client “MobileClient”.


Once you do this, LightSwitch will upgrade your project to support the new features in Preview 2. Keep in mind, once you upgrade the project, you will not be able to open it on another machine unless you have the Preview 2 installed.

Add a “Home” Screen

When users first open the application we want them to see a list of current projects, just like they see on the Home screen on the desktop app. To add a screen, right-click on the MobileClient (which is now set as your startup project for debugging) and select “Add Screen…”.


This will open up the Add New Screen dialog. Select the Browse Data Screen template, then select the CurrentProjects query as the Screen Data and name the screen “Home”. Then click OK.


The Screen Designer will open. Because this particular query has an optional parameter that retrieves all projects in the system, LightSwitch will place the parameter input on the screen as well. In this case, we want only the current projects displayed so delete this control.


If you hit F5 to run the app at this point, we’ll now see the list of current projects on the home screen.


Add a View Details Screen

Now we want to display a screen that shows the project details as well as the photos. So right-click on the MobileClient and “Add Screen…” again. This time select the View Details Screen template. Select Project as the screen data and then make sure to include the related Pictures.


On this screen we also want the mobile user to be able to update the notes field if they need to. So change the Notes field to a TextArea control.


Wire Up the Tap Event

In order to open the details screen we’ll need to wire up the tap event of the list box on the Home screen. Open the Home screen, select the Current Project list and in the Properties window under Actions, add a Tap action by clicking the link.


This will pop up a dialog that let’s us call up the details screen. Select “Choose an existing method” then select “showViewProjectDetail”. Finally, you will need to specify that the CurrentProject.selectedItem should be sent to the details screen.


Now if we hit F5 to run this we can tap on a project in the list and the View Project Detail screen will appear. Notice that the child relation to the Pictures is automatically displayed on a separate tab.


Displaying Images in Tiles

Next we want to display the photos in a tiled list when the user opens the Pictures tab. Open the ViewProjectDetail screen and first set the Picture summary control to a Rows layout. This will display the image & the notes controls.


Next change the List control to a Tile List control.


Hit F5 to run the application, select the first project then select the Pictures tab and you will see the tiled list of picture thumbnails.


Add a Dialog to Upload Pictures

Now it’s time to add the main part of functionality to this app. We want to allow users to upload new photos. Right now using Preview 2 we need to add some custom code to do this. Luckily all the code we need is part of the HTML Client tutorial. There are a couple files we need from this project to incorporate into ours:

Sample Resources\image-uploader.js
Sample Resources\image-uploader-base64-encoder.aspx

We need to add these to our client project manually. In order to do this simply flip to “File View” which allows you to see the physical layout of the solution.


Next, open up the MobileClient node and add an existing file to the \Scripts node.


Select the image-uploader.js and the image-uploader-base64-encoder.aspx. Next open up default.htm located in the root by double-clicking on it and add the following reference at the end of the script block:

<script type="text/javascript" src="Scripts/image-uploader.js"></script>

Flip back to Logical view and then open the ViewProjectDetail screen. Select the Dialogs node at the bottom, and then select and select Add Dialog. In the Properties window, change the dialog’s Name to ImageUploader.


From the left-hand side of the Screen Designer (the view model), drag the SelectedItem node of Pictures into the new dialog. Delete the Project item.


Next select the newly-added Selected Item node. In the Properties window, set both Width and Height to Fit to Content. Change Note’s type to Text Area.


Next, the fun part -- writing some JavaScript code :). Switch the dialog’s Picture field from an Image to a Custom Control.


In the Properties window, choose the Edit Render Code hyperlink or select the “Write Code” button at the top right of the designer and select the _render method.


Add the following code (in bold):

myapp.ViewProjectDetail.Image1_render = function (element, contentItem) {
    // Write code here.
    createImageUploader(element, contentItem, "max-width: 300px; max-height: 300px");
The call redirects all of the heavy-lifting to the image-uploader.js file we added. The customizable styling statement ("max-width: 300px; max-height: 300px") specifies the image preview size. Now all we need to do is call up this dialog. Let’s add a button on the screen tab to do this. Select the Pictures tab and select Add, New Button.


In the Add Button dialog box, choose the Pictures.AddAndEditNew method, and Image Uploader as the “Navigate To” dialog.


Set Data Default Value

Next we need to add code in order to set the “Updated” field automatically when a picture is uploaded. This is a specific requirement of Contoso Construction’s schema, the Picture.Updated field is required, but it’s internal so it’s not displayed on the screen. Select the Projects entity to open the Data Designer. You will notice at the bottom of the Data Designer there are now different perspectives. The Server perspective is where all your business logic resides. This is the middle-tier data services and is where “the buck stops here” code resides like data validation and complex data processing. This is why we can add an HTML client to an existing project with minimal code, because most of your code is here.

In order to add default values on our HTML client, select the “MobileClient” view and then select the Updated field. Then drop down the “Write Code” button and select “created” method. This allows you to set defaults on the JavaScript client.


Write this code (in bold):

myapp.Picture.created = function (entity) {
    // Write code here.
    entity.Updated = new Date();

RUN IT! When we F5 to run our application, navigate to a project, then select the pictures tab, we can now click the “Add Picture” button at the bottom of the screen to add a new image and some notes.


Clicking the checkmark at the top right will enter the new picture into the list. When you’re done uploading images, click the Save button on the top right of the screen to save them all.


Note that if the user tries to navigate away from the screen, they will be prompted to save or discard changes just like you would expect.

Add the Company Logo

Finally, let’s add the company logo to the mobile client so this looks professional and company branded. Flip to file view in Solution Explorer. Then expand the MobileClient project node and look under Content/Images and you will see a user-logo.png. Simply replace that file with the logo you want.


You can also replace the user-splash-screen.png in order to display a different image when the application is loading. Now when we run the application, we’ll see the Contoso Construction icon in the upper left of the Home screen.


Deploy to Azure Website

Now that we have our HTML client application we can deploy it in 3 minutes to an Azure Website like I showed here:
Easily Deploy Your LightSwitch Apps to Azure Websites in Minutes

I also encourage you to work through the HTML Client tutorial to see end-to-end how to build an HTML companion client & deploy it to Azure. Once the app is deployed to the internet, the construction crew can now use the HTML client app on their smart phones and tablets.

Wrap Up

As you can see, LightSwitch makes it super simple and fast to build HTML clients. You only need to know a little HTML5 & JavaScript to customize the UI like we did in order to add customizations. LightSwitch has always been able to focus the developer on writing code that provides the business value (custom controls, business rules) and not have to worry about all the plumbing (data access, service implementations, etc). This still holds true with the addition of the HTML client.

Try it out and let us know what you think.


Leave a Comment
  • Please add 3 and 7 and type the answer here:
  • Post
  • Excellent work. Very short and to the point with good screen shots and accomplishes a lot!

  • A few questions.  Is the HTML client only for mobile?  Can I use it to make an application with only an HTML client and no Silverlight?  Unfortunately Silverlight is now banned at our work because of the uncertainty with no future roadmap.  Is it possible to make a multi-lingual HTML client?  That's another show stopper for us  right now with Lightswitch.

  • Thanks again.

  • Excellent article. But still love Silverlight way ;)

  • Excellent article. However, like Marc-Andre, I am a bit surprised that HTML seems to mean mobile with Tiles. We have lots of customers that expect us to other GUIs instead of drawing a couple of tiles with text. I have not seen a single user who said: Wow, tiles...great.

    Will there some sort of customization possible?

  • @Marc-Andre, @holger - yes you can build an HTML client-only app with LightSwitch. We are using JQuery mobile under the hood so that you can run the app on the most devices available and we are optimizing for touch-enabled mobile devices and tablets. However you can customize the client with your own JavaScript & controls. We're just in preview now but expect to see more capabilities in the future. See this thread for details:

    I encourage you to keep sharing your feedback in this space by visiting the forum -- the team is listening:



  • How does the file browse function work on mobile devices? Does it default to the "camera roll"? Does it only allow you choose a file location or will it allow the camera to launch as well?

    On a seperate but related note, is there a method that can be used to capture signatures?

  • Anwsered my own question by try... It works well with iOS and Andriod browsers. Ironically, I'm unable to get the "image-uploader" custom control to work for WP8 browsers. Tried several browsers on WP8 but none of them will function correctly.

  • @Jim W - Yes unfortunately the file upload isn't supported in WP browsers yet. Here's a compatibility chart:

    For the signature, take a look at this post:

  • Thanks for the "Signature for HTML" post. Its very helpful and adds a ton of value to our projects.

    1000 Thanks!

  • Thanks for the article.

    I'm testing this example with VS 2013 Pro, and after fixing the problems with the extensions, I run it, but the popup for Image Uploader is not editable, all the controls are like in read only mode, I've no idea how to fixed it. (I check that "Use Read-only Controls" is not activated)

    Any advice?

  • Great article thanks, I wanted to know if it was possible to connect an IP Camera to capture an image as an addition to the file uploader.


Page 1 of 1 (12 items)