Building an HTML Client for a LightSwitch Solution in 5 Minutes

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.

image

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…”

image

 

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

image

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…”.

image

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.

image

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.

image

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

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

Next change the List control to a Tile List control.

image

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.

image

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.

image

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

image

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.

image

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.

image

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.

image

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

image

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.

image

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.

image

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

image

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.

image

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.

image

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.

image

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.

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.

image

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.

image

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.

Enjoy!