Up until now, this book has focused on building user interfaces with LightSwitch’s Silverlight client. By installing an update to Visual Studio, you can build applications that use an HTML interface. The biggest benefit is that it allows you to build applications that work well on mobile devices. In particular, the “HTML client” produces screens that are optimized for touch-screen devices.

In this chapter, you’ll learn how to

• Add an HTML client, create screens, and build a navigation structure
• Show and edit data by using custom HTML controls
• Customize your application by adding CSS (Cascading Style Sheet) and JavaScript code

This chapter shows you how to build an HTML interface to the HelpDesk application. You’ll find out how to build screens that allow engineers to add, view, and edit issues. You’ll also find out how to allow users to upload and download files, replace the default Date/Time Picker control with a custom control, and apply different fonts and colors to your application by using themes.

Introducing the HTML Client

The ability to build HTML clients is a big step in the evolution of LightSwitch, allowing you to reach a far wider range of devices. In comparison, a Silverlight browser application requires the user to install the Silverlight runtime. This isn’t always possible, particularly on mobile devices or locked-down corporate environments. A disadvantage of the HTML client is that it isn’t suitable for all scenarios. If you’re targeting your application at PC users and require rich features, such as output to Excel and COM automation, Silverlight is still the best choice.

One of the features of LightSwitch is that it builds applications that are based on industry standards and best practices. In Chapter 1, you learned how LightSwitch uses an n-tier architecture and is based on the MVVM pattern. The HTML client is also based on a “layered” architecture and uses libraries that are well known and popular with web developers.

As Figure 8-1 shows, LightSwitch HTML client applications are based heavily on jQuery. It uses the controls in the jQuery Mobile library, and it uses the datajs library to access your server through OData. It uses a small, cross-browser-compatible subset of the WinJS library. This is a JavaScript library that’s primarily designed to help build browser applications that target Windows 8. Developing an HTML client application is very similar to developing a Silverlight application—the underlying concepts (such as screens, entities, content items, and controls) are identical. However, there are a few fundamental differences that you need to understand.

Whereas the Silverlight client allows users to open multiple screens and carry out multiple tasks at the same time, HTML clients are designed to carry out just a single task at any one time. In previous chapters, you learned how each screen includes a data workspace, and how each screen carries out data operations independently of other screens. This concept doesn’t apply to the HTML client. The HTML client includes just one data workspace for your entire application.

Just like the Silverlight client, an HTML client application consists of screens. Each screen that you create centers on a unit of work and is generally based on an entity or a collection of data. Each screen can contain one or more tabs. Tabs allow you to split a screen into separate sections. At runtime, a user can switch between tabs by using links that appear at the top of your screen.

Compared to the Silverlight client, the HTML client makes it easier to share UI elements across multiple screens through dialogs. To create a dialog, you’d create a screen as normal, but configure it so that LightSwitch shows it as a dialog. When a user opens a dialog, LightSwitch displays the screen content in a floating panel and darkens the underlying screen area.

Another piece of UI that’s new to the HTML client is the popup. A popup is a floating piece of UI that’s perfect for showing messages or confirmations. Whereas a dialog takes up almost all of the available screen area, popups are generally smaller in size. When LightSwitch shows a popup, it doesn’t darken the underlying screen, as in the case of a dialog. To dismiss a popup, a user would click on an area of the screen outside of the popup. Popups are screen-specific, so there’s no way to share popups between screens.

Setting Up Visual Studio for HTML Development

To develop HTML client applications, you first need to install an update called “Visual Studio 2012 Update 2.” You can download and install this from the following URL:

http://www.microsoft.com/en-us/download/details.aspx?id=38188

Once you install this update, you can begin to develop HTML client applications.

Adding an HTML Client

There are two ways for you to create an application that includes an HTML client. You can either create a brand new “LightSwitch HTML Application” by using Visual Studio’s File New Project option, or you can add an HTML client to an existing Silverlight LightSwitch project.

To do the latter, right-click your LightSwitch project and choose the “Add Client” option. This opens the Add Client dialog, as shown in Figure 8-2.

Once you add an HTML client, Visual Studio upgrades your project. This process creates a new project file with an ls3proj extension and upgrades your application’s model schema from v2 to v3.

Once the upgrade process finishes, your new HTML client project becomes your startup project. This means that when you debug your application by pressing F5, Visual Studio runs your HTML client project. If you want to debug and run your Silverlight client, right-click your Client project in Solution Explorer and select the “Set as StartUp Client” option.

If the “Add Client” dialog fails to add an HTML client, try upgrading your project independently, and then try adding an “HTML client” again. You can perform an independent upgrade by right-clicking your project in Solution Explorer and choosing the “Upgrade Project” option.

Adding Screens to Your Application

Once you add an HTML client, you can start to add screens to your application. To do this, right-click your HTMLClient in Solution Explorer and choose the “Add Screen” option. This opens the “Add New Screen” dialog, as shown in Figure 8-3.

This dialog looks very similar to the Add New Screen dialog that you’re familiar with, but notice how it contains fewer screen templates. The screen templates that appear are self-explanatory. The Browse Data Screen template creates a screen that shows a collection of entities through a List control.

The List control allows you to specify the action that occurs when a user selects an item in the control. It allows you to open the selected entity in a View Details Screen or Add/Edit Details Screen.

The View Details Screen template builds a screen that’s designed to show a read-only view of data, whereas the Add/Edit Details Screen template creates a screen that allows users to edit data.

Designing Screens

Following on from Chapter 7, you won’t have any difficulty in understanding how to design and customize HTML screens. This is because LightSwitch provides a screen designer that looks almost identical to the one that you’ve used before. Many of the concepts are the same—you still design screens using the hierarchical Screen Content Tree, Screen Members still appear in the left panel, and you can still add queries and local properties by clicking on the Add Data Item button.

Despite these similarities, the HTML designer introduces some different layouts and controls. This section describes the differences that you’ll find in further detail.

Creating a Navigation Structure

Any serious application includes more than one screen, so you’ll need to provide a way for users to navigate your application. In this section, you’ll find out how to create a startup screen, how to allow users to open screens, and how to show popups and dialogs.

Adding New Records

Unlike the Silverlight client, there isn’t a screen template that allows you to create screens for the sole purpose of adding records. Instead, you’ll need to create a screen that uses the Add/Edit Screen Details template. So to add a screen that allows users to add records, create a screen that’s based on the Issue table and name it AddEditIssue. In the “Add New Screen” dialog, use the check box to include the “Issue Response” data—you’ll use this data collection in the next section.

Once you do this, you can configure the CreateNewIssue button on your setup screen to open your AddEditIssue screen by using the “Edit Tap Action” dialog (Figure 8-11). When this dialog opens, select the “Choose an existing method” radio button and choose the showAddEditIssue option from the “Navigation Group.” LightSwitch detects that you’ve selected an Add/Edit screen and shows a text box that allows you to enter the entity that you want to work with. Enter “(New Issue)” into this text box to configure your button to open your Add/Edit screen in Add mode.

When you now run your application and click on your “Create New Issue” button, LightSwitch will open your Issue Detail screen in Add mode.

Using Dialogs

Dialogs are modal screens that “open up” and float above an existing screen. When LightSwitch shows a dialog, it darkens the existing screen, which is still visible beneath. Dialogs are perfect for adding UI elements that you can reuse on multiple screens. To create a dialog, simply create a screen and check the “Show as Dialog” check box in the properties sheet, as shown in Figure 8-8.

Dialogs are a great way to allow users to add and edit child records. This section shows you how to create a dialog that allows users to add and edit the child issue response records that relate to an issue record.

To create this example, add a new screen that uses the “Add/Edit Details Screen” template, and base it on the IssueResponse table. Name your screen AddEditIssueResponse. Once you create your screen, select the root node of your screen use the properties sheet to check the “Show As Dialog” check box.

Using Popups

Popups are similar to dialogs. They allow you to show UI controls in a modal panel that appears above an existing screen. The main difference between a popup and dialog is that popups are defined at a screen level and you can’t share them across multiple screens. Unlike its treatment of dialogs, LightSwitch doesn’t gray out the underlying screen when it shows a popup, nor does it show OK and Discard or Save buttons. To close a popup, a user would click on a screen area outside of the popup. Another characteristic is that LightSwitch doesn’t center-align popups in the same way as dialogs.

To demonstrate how popups work, here’s how to attach a popup to your issue screen that shows additional details about the engineer who has been assigned to the issue. To create this example, carry out the following steps:

1. Open your AddEditIssue screen in the screen designer, and create a new popup by clicking on the “Add Popup” button that appears beneath the popups folder. Open the properties sheet, and set the name of your popup to AssignedEngineerPopup.
2. Drag the Issue entity’s AssignedTo property onto your popup. By default, LightSwitch renders the AssignedTo property as a “Details Modal Picker” control. Use the dropdown to change the control type to a Rows Layout.
3. Open the properties sheet for your Rows Layout, and check the “Use Read-only Controls” check box that you’ll find in the General section. You can tidy up your popup view by deleting the engineer property controls that you don’t want to show.
4. In the main part of your screen, add a new button. When the “Add Button” dialog appears, select the “Choose an existing method” radio button and use the dropdown to select the showPopup option. Use the dropdown to select the “Assigned Engineer Popup” choice. Set the display property of your button to “Show Assigned Engineer Details.” Figure 8-15 shows how your screen should now look.

You can now run your screen, and Figure 8-16 shows how it looks. When a user edits an issue and sets an “Assigned To” engineer, the “Show Assigned Engineer Details” button allows the user to view the selected engineer in a popup.

This example demonstrates how popups are ideal for showing additional pieces of information on a screen. In Figure 8-16, also notice how the popup docks itself to the location of the button rather than aligning the content in the center of the screen (as in the case of a dialog).

Creating a Search Screen

Although LightSwitch doesn’t include a search screen template, you can easily create a search screen by creating a Browse Data Screen that’s based on a query. In fact, the process is identical to the “Creating an Advanced Search Screen” example that you saw in Chapter 7. You won’t find it difficult to create a search screen, so this chapter focuses on showing you how to add search capabilities to your application by demonstrating how to allow users to filter the choices in the List control.

Filtering the List Control

Earlier in this chapter, you saw how difficult it is for users to assign an engineer to an issue by using the “Modal Window Picker” control. This is particularly the case if the control contains hundreds of engineers’ records (Figure 8-7). This section shows you how to create a dialog that users can use to find engineers by name. You can then call this dialog from your AddEditIssue screen to make it easier for users to assign an engineer to an issue.

To begin, you’ll need to create a query that returns engineer records where the surname or first name matches the value of a parameter called Name. Create the query that’s shown in Figure 8-18, and name your query EngineersByName.

Once you’ve added your query, carry out the following steps to create your dialog:

1. Create a new “Add/Edit Details Screen” that’s based on the Issue table, and name your screen EngineerPicker.
2. In the properties sheet for the root node of your EngineerPicker screen, set the display property to “Find Engineer” and make sure that you select the “Show As Dialog” check box. (This is the default option.)
3. Delete all of the Issue property controls on the screen, except for the AssignedTo property.
4. Click on the “Add Data Item” button, and add a local string property called EngineerName. Make sure to uncheck the “Is Required” check box.
5. Drag the EngineerName property from the screen member list onto your screen, above the AssignedTo “Details Modal Picker.”
6. Click on the “Add Data Item” button, and add your EngineersByName query.
7. Set the “Parameter Binding” for the EngineersByName query’s Name parameter to the EngineerName property. (If you need some help on binding parameters, refer to the “Creating an Advanced Search Screen” section in Chapter 7.)
8. Open the properties sheet for your AssignedTo “Details Modal Picker.” Change the Choices setting from Auto to EngineersByName.
9. Change the control that appears beneath your “Details Modal Picker” from a Summary Control to a Columns Layout. Delete the properties beneath the Columns Layout so that only the Firstname and Surname properties remain. This completes the design of your “Engineer Picker” dialog, and Figure 8-19 shows how your screen now looks.

   

   Figure 8-19. Designing the EngineerPicker Dialog

    Note  You might wonder why you’ve replaced the Summary Control with a Columns Layout that includes the engineer’s first name and surname. Why not keep the Summary Control, and use it to show the full-name computed property that you defined in Chapter 2? The reason is because the HTML client doesn’t support computed properties. Computed properties are defined with .NET code, and therefore, the JavaScript HTML client can’t derive the result of a computed property value on the client.

   Now that you’ve created your Engineer Picker dialog, you’ll need to carry out the following step in your Issue screen to allow users to open your Engineer Picker dialog:

10. Open your AddEditIssue screen, and add a new button beneath the AssignedTo property. When the “Add Button” dialog appears, select the showEngineerPicker option and select Issue in the Issue text box (Figure 8-20). In this context, Issue refers to the local Issue property on your screen. Set the display name of your button to “Find Engineer.”

    

    Figure 8-20. Opening a Dialog

You’re now ready to run your application, and Figure 8-21 shows what your screen looks like at runtime.

When the user opens an issue and clicks on the “Find Engineer” button, LightSwitch opens the “Find Engineer” dialog that allows the user to enter a name. This allows the user to enter an engineer name, and Figure 8-21 illustrates a case where the user enters “el” into the engineer name search box. When the user clicks on the “Assigned To” control that’s below the engineer name search box, LightSwitch shows a list of engineer records where the surname or first name contains the text that’s been entered by the user (in this case, “el”). This filtered list makes it much easier to find an engineer, compared to forcing the user to find an engineer by scrolling through a list of hundreds of records.

This example also illustrates a case where a dialog works better than a popup or a tab. In this scenario, a dialog provides a center-aligned piece of UI that looks neater than a popup. When the user clicks on the “Assigned To” Details Modal Picker in the “Find Engineer” dialog, LightSwitch opens the list of available choices in a center-aligned panel that appears above everything else on the screen. By using a center-aligned dialog, you can be certain that the “Details Modal Picker” appears directly above the dialog, therefore drawing the user’s attention to the “Assigned To - Details Modal Picker.”

Another advantage is that dialogs include a cancel button. So if a user makes a mistake in the “Find Engineer” dialog and selects the wrong engineer, they can easily undo their change by clicking on the cancel button.

Extending Your Application with JavaScript

The HTML client allows you to customize your applications by writing JavaScript. This allows you to add custom logic (for example, client-side validation), customize the UI that’s shown to the user, bind data to custom controls, and interact with data.

If you’ve used earlier versions of Visual Studio, you’ll be pleasantly surprised at how well Microsoft has improved its support for JavaScript. The IDE provides full IntelliSense when you’re writing JavaScript. It auto-completes and provides tooltip descriptions for most of the JavaScript objects that you’ll encounter. This includes IntelliSense support for local screen properties and custom entities, as shown in Figure 8-22.

Another improvement is that breakpoints now work as you’d expect them to work. In contrast to previous versions of Visual Studio, you don’t need to mess about with enabling debugging in Internet Explorer or attach your Visual Studio debugger to your browser process. You can simply place breakpoints in your JavaScript code, press F5, and go!

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
/// <reference path="../GeneratedArtifacts/viewModel.js" />
  
myapp.AddEditIssue.created = function (screen) {                    
    if (screen.Issue.Id == undefined) {                             
        screen.Issue.CreateDateTime = new Date();                   
    }
};

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.created = function (screen) {
    if (screen.Issue.Id == undefined) {                             
        screen.details.displayName = "New Issue";                   
    } else{
        screen.details.displayName = screen.Issue.Subject;          
    }
};

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.created = function (screen) {
    if (screen.Issue.Id == undefined) {
        screen.findContentItem("ClosureDetails").isVisible = false;
    }
};

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.ClearAwaitingClient_execute = function (screen) {
      
    for (var i = 0; i < screen.IssueResponses.count; i++) {              
        var issResp = screen.IssueResponses.data[i];                     
        issResp.AwaitingClient = false;                                  
    }
};

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.created = function (screen) {
  
   //1 add a change listener to the ClosedDateTime property                       
   screen.Issue.addChangeListener("ClosedDateTime",
      function (e) {
  
         //2 this code runs each time ClosedDateTime changes                      
         var issue = screen.Issue;                                                
  
         var contentItem = screen.findContentItem("ClosedDateTime");              
  
         if (issue.CreateDateTime != undefined &&
         issue.ClosedDateTime < issue.CreateDateTime) {

            contentItem.validationResults = [
               new msls.ValidationResult(
                  screen.Issue.details.properties.ClosedDateTime,
                  "Closed date can't be earlier than create date")];              
         }
   });
};

Adding Custom HTML to Screens

One of the beauties of HTML client applications is that you can customize almost all parts of your screen. The only exception is the heading section. To demonstrate this feature, this section shows you how to add custom images, text, and hyperlinks to a screen, as illustrated in Figure 8-31.

To create this example, open your AddEditIssue screen in the designer and select the Rows Layout that corresponds to the first tab on your screen. By default, LightSwitch names this control Details. Click on the “Add Code” button, and choose the Details_postRender method. Now add the code that’s shown in Listing 8-7.

Listing 8-7.  Adding Custom HTML to a Screen

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.Details_postRender =
    function (element, contentItem) {                                               
  
        var helpText = $("<div style='padding-bottom:20px;'>" +                     
            "<img src='Content/Images/Info.png' style='float:left;padding-right:10px;'/>" +
        "Use this screen to enter a new issue.<br/>" +
        "<a href='http://intranet/help.htm' target='_blank'>Click here</a>" +
        " for more help.</div>");
  
    helpText.prependTo($(element));
  
    };

The postRender method includes a parameter called element . This represents the HTML markup that has been built by the HTML client. In this example, element contains the HTML markup that represents the Details group.

This code builds the new content that you want to add in a variable called helpText . This content includes a DIV (an HTML Division element) that contains an image tag, help text, and a hyperlink. This HTML represents the content that’s shown in Figure 8-31. For the image to display correctly, you’ll need to create an image called Info.png and add it to your HTML client’s ContentImages folder. You can add resources such as images by switching your project to File View and using the “Add” option in Solution Explorer. The final part of the code adds this HTML to the beginning of your Details Group by calling jQuery’s prependTo method.

As you can see, the helpText contains a fair amount of presentational data in the style attributes. To improve this code, you could apply your own CSS classes and include the style definitions in a CSS file.

Using Custom Controls

As with the Silverlight Client, you’re not limited to using the built-in controls that LightSwitch supplies. If there isn’t a built-in control that looks or behaves exactly as you want, you can overcome this limitation by building your own custom control.

This section consists of two main parts. In the first part, you’ll learn how to use custom controls to show data in a read-only format. In the second part, you’ll learn how to create a fully interactive custom control that data-binds to your underlying data source. Technically, this two-way data binding requires you to carry out two distinct tasks. First, you need to run code that responds to changes in the value of your underlying data item. This allows you to write code that updates the display of your custom control. Second, you need to write code that reacts to user interaction and updates the value of your underlying data item.

Let’s take a closer look at how you’d set up a custom control. To define a custom control, use the screen designer’s dropdown to set the control type for a data item to “Custom Control” (Figure 8-32). The next step is to write JavaScript in your custom control’s render method that defines the HTML for your control. The render method includes a parameter called ContentItem that allows you to access the data that your custom control binds to.

The “level” at which you create a custom control is very important because it determines the data that you can access in code. If, for example, you set the control type of the ProblemDescription property to a custom control, the ContentItem parameter gives you access to the ProblemDescription property only. If you want to create a custom control that shows both the Problem Description and the Target End Date, you wouldn’t be able to accomplish this by using a custom control that binds to the ProblemDescription property. To access more than one property from an entity, you’d need to create a custom control that binds to the entity. So, in this example, you’d change the parent Rows Layout to Custom Control. This means that your custom control’s ContentItem parameter gives you access to the Issue property, which in turn allows you to access both the Problem Description and Target End Date values.

File:HelpDeskVBHTMLClientUserCodeBrosweIssues.js
  
myapp.BrowseIssue.IssuesTemplate_render =
    function (element, contentItem) {
    //RowTemplate
    var overdueAlert = "";
    var today = new Date();                                                             
    if (contentItem.value.TargetEndDateTime < today) {                                  
        overdueAlert =                                                                  
            "<img src='Content/Images/Warning.png' " +
            "style='float:left;padding-right:10px;'/>";
    }
  
    var customText = $("<div>" + overdueAlert + "<p><strong>" +                         
       moment(contentItem.value.CreateDateTime).format('ddd MMM DD YYYY') +
       "</strong></p></br>" +
       contentItem.value.Subject + "</div>");
    customText.appendTo($(element));
};

Running Code When Data Changes

The previous example showed you how to display data by using a custom control. If you want to do anything more sophisticated, you’ll need to know how to update data in addition to showing it. You can accomplish this by calling a method that the contentItem object exposes called dataBind. This is a powerful method that allows you to bind JavaScript functions to data items.  

To introduce how the dataBind method works, this section shows you how to run code when the value of a data item changes. The following example shows you how to modify your Add/Edit Issue screen so that when a user enters a new issue, it’ll trigger custom code that sets the target end date of the issue to 3 days after its create date. The advantage of the data-binding technique is that the HTML client automatically updates the target end date as soon as the user changes the create date. And it’ll do this every time that the user subsequently changes the create date.

To create this example, open your AddEditIssue screen and select the Rows Layout that contains the controls that relate to your Issue property. By default, this group is called Details. Click on the “Add Code” button, and choose the Details_postRender method. Now add the code that’s shown in Listing 8-9.

Listing 8-9.  Running Code When Data Changes

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.Details_postRender = function (element, contentItem) {
  
    // 1 databind the createDateTime                                              
    contentItem.dataBind("screen.Issue.CreateDateTime", function () {
        setTargetEndDate(contentItem);
    });

    function setTargetEndDate(contentItem) {
  
        // 2 only set the target date for new issues                              
        if (contentItem.screen.Issue.Id == undefined
             && contentItem.screen.Issue.CreateDateTime != undefined) {
  
            // get the create date
            var createDate = contentItem.screen.Issue.CreateDateTime;
            var futureDate = new Date(createDate.getFullYear(),
                                createDate.getMonth(), createDate.getDate());
  
            // add 3 days onto the create date
            futureDate.setDate(futureDate.getDate() + 3);                         
            contentItem.screen.Issue.TargetEndDateTime = futureDate;              
        }
    };
};

The first part of this code uses the dataBind method to bind the CreateDateTime property to a method called setTargetEndDate . The screen object allows you to access the issue’s CreateDateTime property, so the valid binding path that you would use is screen.Issue.CreateDateTime. This data binding means that LightSwitch will call the setTargetEndDate method each time the CreateDateTime property changes.

The setTargetEndDate method tests whether the user is creating a new record, and it also checks that the user has set a create date . If so, it creates a variable called futureDate and uses JavaScript’s setDate method to set the value to three days after the create date . Finally, the code sets the TargetEndDateTime to the future date .

Replacing Default Controls with Custom Controls

Now you know how to use the dataBind method, you can begin to create even more sophisticated custom controls. This example shows you how to replace LightSwitch’s Date/Time Picker with a third-party date-picker control that data-binds to your data item in both directions.

The third-party control that you’ll use is provided by a company called Mobiscroll. However, you could use any other HTML control instead—the principles would remain the same.

In this example, you’ll bind the Issue’s CreateDateTime to an HTML input box and attach the Mobiscroll “Date & Time Scroller” control to this input box. Figure 8-37 shows what your screen looks like when you complete this example.

To create this example, carry out the following tasks:

1. Download the Mobiscroll control from the following web site: http://download.mobiscroll.com/datetime. At the time of writing, this control is free; however, the suite contains several other controls that you must pay for.
2. The Mobiscroll package includes two files: a CSS file and a JavaScript file. Switch to File View, and add these files to a new folder in the following location in your HTMLClient project: HTMLClientContentmobiscroll.
3. While you’re still in File View, open the default.htm file that you’ll find in the root of your HTMLClient project. The head section of this file contains links to CSS files. Before the end of the head section, add a link to the Mobiscroll CSS file. Your link will look like this:

   <link rel="stylesheet"  href="Content/mobiscroll/mobiscroll.datetime-2.4.1.min.css" />

4. The body section of your default.htm file contains links to script files. Before the end of the body section, add a link to the Mobiscroll JavaScript file. Your link will look like this:

   <script src="Content/mobiscroll/mobiscroll.datetime-2.4.1.min.js">
   </script>

This completes all of the tasks that are needed in your default.htm file. If Mobiscroll releases a newer version of its controls, or if you’ve saved the CSS and JS files in a different location, you can adapt the file names that are specified in steps 3 and 4. Now switch your project to Logical View and carry the following steps:

1. Open your AddEditIssue screen in the screen designer.
2. Change your CreateDateTime control from a Date/Time Picker to a custom control.
3. Select your CreateDateTime control, click on the “Edit Render Code” link in the properties sheet, and add the code that’s shown in Listing 8-10.

Listing 8-10.  Adding the Mobiscroll Control

File:HelpDeskVBHTMLClientUserCodeAddEditIssue.js
  
myapp.AddEditIssue.CreateDateTime_render =
function (element, contentItem) {
    var CreateDateTime =
        $('<input id="CreateDateTime" type="datetime"/>'),
    CreateDateTime.appendTo($(element));                                      
  
    // 2 Initialize the mobiscroll control                                    
    $(function () {
        var now = new Date();
        $('#CreateDateTime').mobiscroll().datetime({
            minDate: new Date(now.getFullYear() - 10,
            now.getMonth(), now.getDate()),
            dateFormat: 'yy-MM-dd HH:mm',
            theme: 'default',
            lang: ' ',
            display: 'modal',
            animate: ' ',
            mode: 'scroller'
        });
    });
  
    // 3 Listen for changes made in the view model                            
    contentItem.dataBind("value", function (newValue) {
        // Update the HTML Input and Scroller Control
        CreateDateTime.val(moment(newValue).format('YYYY-MM-DD HH:mm'));      
        $("#CreateDateTime").scroller('setDate', newValue , true);            
    });
  
    // Listen for changes made via the custom control
    CreateDateTime.change(function () {
        // update the content item value
        var newDate = moment(CreateDateTime.val(), "YYYY-MM-DD HH:mm");
  
        if (contentItem.value != newDate.toDate()) {
            contentItem.value = newDate.toDate());                            
        }
    });
};

After you’ve added this code, you can run your application. The code at the start of the render method creates a variable called CreateDateTime, and sets its value to the HTML markup that represents an HTML input control. It then renders it on screen by appending CreateDateTime to the render method’s element parameter . This piece of code is necessary because the Mobiscroll control technically works by attaching itself to an HTML input.

The next part of the listing contains code that’s specific to the Mobiscroll control . It initializes the Mobiscroll control by setting default attributes. This includes the minimum date that the user can select (it sets this to ten years before today’s date), theme settings, and language settings. For more information, the Mobiscroll documentation shows you all of the attributes that you can use.

The code in the next section calls the content item’s databind method . This allows your control to react when the underlying value changes and to update the value of the HTML input control by calling a Mobiscroll method called scroller . This method sets the value of the Mobiscroll control to the new value.

The next section adds code that executes when the value of the HTML input changes. When this happens, it sets the underlying value of the content item to the new value . This section of code uses the momentjs library to test that the date has changed before updating the underlying content item value.

Uploading Files

The HTML client doesn’t include a file upload control, so you’ll need to create a custom file-upload mechanism. An efficient way to provide this capability uses the File API capabilities that you’ll find in HTML5 browsers. The HTML5 standard allows web browsers to interact with local files. This is a really powerful feature because it enables you to work with files on the client, before you send them to the server. For example, you could validate data or create thumbnails of images on the client. Figure 8-40 illustrates the process that you’ll carry out in the form of a diagram.

This process relies on a custom control that you’ll create. This custom control consists of two elements: a file browse button (that is, an HTML Input of type file), and a DIV that shows the results.

When the user selects a file, the control uses the local file-processing feature of the HTML5 browser to read the file. It retrieves the contents as a base 64–encoded string, adds the data to the local change set, and shows the results in the DIV. When the user clicks on the save button, the HTML client calls the Data Service’s Save operation. The file that the user adds will be included in the change set that the client sends to the server.

Despite the File API’s ease of use, a big problem is that many users still don’t use HTML5-compliant browsers. Therefore, you’ll need a fallback method to make sure that users with older browsers can still upload files. Figure 8-41 shows how the non-HTML5 file-upload process works.

If the custom control detects that the user isn’t using an HTML5 browser, it generates a control that contains three elements: a file browse button, a hidden iframe, and a DIV to display the progress details. (An iframe is an HTML control that you can use to display a web page inside another web page.)

Once the user selects a file, the control submits the file to an ASP.NET web page through the hidden iframe. The iframe allows the browser to submit the file to the server, without interrupting the user’s ability to interact with the other parts of the screen. The ASPX page mimics the job that the HTML5 File API would carry out—it produces a base 64–encoded representation of the file and returns the result to the client. When the ASPX page finishes loading, the contents of the hidden iframe will contain the base-64 representation of the file. The custom control detects when the iframe finishes loading and displays the result in a DIV, in the same way as the HTML5 custom control.

File:HelpDeskVBHTMLClientContentFileUploaderfile-uploader.js

function createfileUploader(element, contentItem) {
  
    var $element = $(element);
  
    //1 Create either an HTML5 or Non HTML5 control
    if (window.FileReader) {                                                     
        createHTML5Control();
    } else {
        createNonHTML5Control();
    }
  
    //2 This code creates the HTML5 control
    function createHTML5Control() {                                              
        var $file_browse_button = $(
            '<input name="file" type="file" style="margin-bottom: 10px;" />'),
        $element.append($file_browse_button);
  
        var $review = $('<div></div>'),
        $element.append($review);
  
        $file_browse_button.bind('change', function handleFileSelect(evt) {
            var files = evt.target.files;
            if (files.length == 1) {
                var reader = new FileReader();
                reader.onload = function (e) {
                    reviewAndSetContentItem(
                        e.target.result, $review, contentItem);
                };
                reader.readAsDataURL(files[0]);
            } else {
                //  if no file was chosen, set the content to null
                reviewAndSetContentItem(null, $review, contentItem);
            }
        });
    }
  
    //3 This code creates the non HTML5 control
    function createNonHTML5Control() {                                           
        // Create a file submission form
        var $file_upload_form = $('<form method="post" ' +
                'action="../Web/FileUploader/FileUploader.aspx" ' +
                'enctype="multipart/form-data" target="uploadTargetIFrame" />'),
        var $file_browse_button = $(
            '<input name="file" type="file" style="margin-bottom: 10px;" />'),
        $file_upload_form.append($file_browse_button);
        $element.append($file_upload_form);
  
        // The file contents will be posted to this hidden iframe
        var $uploadTargetIFrame = $('<iframe name="uploadTargetIFrame" ' +
                'style="width: 0px; height: 0px; border: 0px solid #fff;"/>'),
        $element.append($uploadTargetIFrame);
  
        // This div shows the upload status and upload confirmation
        var $review = $('<div></div>'),
        $element.append($review);
  
        // Submit the file automatically when the user chooses a file
        $file_browse_button.change(function () {
            $file_upload_form.submit();
        });
  
        // On form submission, show a "processing" message:
        $file_upload_form.submit(function () {
            $review.append($('<div>Processing file...</div>'));
        });
  
        // Once the result frame is loaded (e.g., result came back),
        $uploadTargetIFrame.load(function () {
            var serverResponse = null;
            try {
                serverResponse =
                    $uploadTargetIFrame.contents().find("body").html();
            } catch (e) {
                // request must have failed, keep server response empty.
            }
            reviewAndSetContentItem(serverResponse, $review, contentItem);
        });
    }
  
    //4 This code shows the upload confirmation                                      
    function reviewAndSetContentItem(fullBinaryString, $review, contentItem) {
        $review.empty();
  
        if ((fullBinaryString == null) || (fullBinaryString.length == 0)) {
            contentItem.value = null;
        } else {
            $review.append($('<div>File uploaded</div>'));
  
            //remove the preamble that the FileReader adds
            contentItem.value =
                fullBinaryString.substring(fullBinaryString.indexOf(",") + 1);
        }
    }
}

<script src="Content/FileUploader/file-uploader.js"></script>

VB:
File:HelpDeskVBServerWebFileUploaderFileUploader.aspx
  
<%@ Page Language="VB"%>
  
<script  runat="server">
   Sub Page_Load()
      If Request.Files.Count = 1 Then
         Dim file = Request.Files(0)
         If file.ContentLength > 0 Then
            Dim inputStream = file.InputStream
            Dim base64Block As Byte() =
               New Byte(inputStream.Length - 1) {}
            inputStream.Read(base64Block, 0, base64Block.Length)
                         
            '1 Add the preamble of "data:{mime-type};base64,".             
            Response.Write("data:" & file.ContentType & ";base64," &
                           Convert.ToBase64String(base64Block))
         End If
      End If
    End Sub
</script>
  
C#:
File:HelpDeskCSServerWebFileUploaderFileUploader.aspx
  
<%@ Page Language="C#" %>
  
<script runat="server">
   void Page_Load(object sender, System.EventArgs e)
   {
       if (Request.Files.Count == 1)
       {
           var file = Request.Files[0];
           if (file.ContentLength > 0)
           {
               var inputStream = file.InputStream;
               byte[] base64Block = base64Block =
                  new byte[inputStream.Length];
  
               inputStream.Read(base64Block, 0, base64Block.Length);
  
               //1 Add the preamble of "data:{mime-type};base64,".           
               Response.Write("data:" + file.ContentType +  ";base64," +
                               Convert.ToBase64String(base64Block));
           }
       }
   }
</script>

Downloading Files

The ability to upload files is just one half of this example. Users need some way to retrieve the files that have been uploaded, and you’ll now find out how to implement this feature.

One way to do this is to write JavaScript that uses the LightSwitch’s JavaScript API to retrieve the file content and write the data into a new file on the user’s machine. Downloadify is a utility that can help you accomplish this (https://github.com/dcneiner/Downloadify). It’s a free JavaScript library that allows you to create client-side files by using Adobe Flash.

However, a much easier way to retrieve files from your database is to take advantage of a new feature that the “Visual Studio 2012 Update 2” provides: the Server Application Context API. This is a powerful new feature that allows clients to communicate directly with the LightSwitch logic layer, without having to go through the save or query pipelines. Figure 8-44 shows how the download feature will work.

The Server Application Context API allows you to access your data workspace from custom .NET applications. This, for example, allows you to create ASP.NET or MVC applications that can access your LightSwitch data. You can use the Server Application Context API to add custom functions to your application’s Server project. This example creates a generic ASP.NET HTTP handler that uses the Server Application Context API. A generic handler provides an HTTP endpoint that serves HTTP responses without a UI.

To create a handler that returns the file contents, switch your project to File View. Navigate to your Server project, right-click on the Web folder, and add a new Generic Handler (Figure 8-45). Name your handler DownloadIssueDocument.ashx.

Now modify the contents of this file, as shown in Listing 8-15.  

Listing 8-15.  File Downloader Code

VB:
File:HelpDeskVBServerWebDownloadIssueDocument.ashx.vb
  
Imports System.Web
Imports System.Web.Services
  
Public Class DownloadIssueDocument
   Implements System.Web.IHttpHandler
  
   Sub ProcessRequest(
      ByVal context As HttpContext) Implements IHttpHandler.ProcessRequest
  
       If context.Request.Params("id") IsNot Nothing Then
            context.Response.ContentType = "application/octet-stream"
  
           Using serverContext =
              LightSwitchApplication.ServerApplicationContext.CreateContext()
  
                Dim doc =serverContext.DataWorkspace.ApplicationData.
                    IssueDocuments_SingleOrDefault(
                       context.Request.Params("id"))
  
               context.Response.AddHeader(
                   "Content-Disposition",
                   "attachment;filename=" & doc.DocumentName)
               context.Response.BinaryWrite(doc.IssueFile)

           End Using
  
       End If
  
   End Sub
  
   ReadOnly Property IsReusable() As Boolean Implements IHttpHandler.IsReusable
       Get
           Return False
       End Get
   End Property
  
End Class
  
C#:
File:HelpDeskCSServerWebDownloadIssueDocument.ashx.cs
  
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
  
namespace LightSwitchApplication.Web
{
   public class DownloadIssueDocument : IHttpHandler
   {
      public void ProcessRequest(HttpContext context)
      {
  
         if (context.Request.Params["id"] != null)
         {
            context.Response.ContentType = "application/octet-stream";
            using (var serverContext =
               LightSwitchApplication.ServerApplicationContext.CreateContext())
               {
                  var doc = serverContext.DataWorkspace.ApplicationData.
                     IssueDocuments_SingleOrDefault (
                        int.Parse (context.Request.Params["id"]));
                  context.Response.AddHeader(
                     "Content-Disposition",
                     "attachment;filename=" + doc.DocumentName);
                  context.Response.BinaryWrite(doc.IssueFile);
               }
           }
        }
  
        public bool IsReusable
        {
           get
           {
              return false;
           }
        }
    }
}

The DownloadIssueDocument.ashx handler allows users to download issue documents by URL. For example, the URL http://WebServer/Web/DocumentIssueDocument.ashx?id=8 would return the document that’s stored in the IssueFile property of an IssueDocument record with an id of 8.

To complete this example, you’ll need to add a hyperlink to your AddEditIssueDocument dialog. In the screen designer, select the parent Rows Layout that contains the controls for your IssueDocument property—in this example, the default name of the group is left. In the properties sheet, click on the “Edit PostRender Code” link and add the code that’s shown in Listing 8-16.

Listing 8-16.  Button Code That Calls DownloadIssueDocument.ashx

File:HelpDeskVBHTMLClientUserCodeAddEditIssueDocument.js
  
myapp.AddEditIssueDocument.left_postRender =
  
function (element, contentItem) {
   if (contentItem.value.Id != undefined) {
  
      var downloadURL = '../Web/DownloadIssueDocument.ashx?id=' +             
         contentItem.value.Id.toString();
  
      var downloadLink = $('<div><a target="_blank" ' +                       
          'href="' + downloadURL + '" style="margin-top: 10px;" >' +
          'Download Document File</a></div>'),
      downloadLink.appendTo($(element));
   }
};

This code builds a hyperlink and appends it to the end of your Document dialog. The first part of this code creates the URL that points to the DownloadIssueDocument.ashx address and appends the Id value of the selected document record to the URL . The code sets the target attribute to _blank . This prompts the browser to open the hyperlink in a new window. If you didn’t add this attribute, the hyperlink would navigate the user away from your LightSwitch application. The final piece of code appends the hyperlink to the end of the Rows Layout.

This code works on the basis that you deploy your HTML application to the following URL: http://yourServer/HTMLClient. The default address of your handler will be this: http://yourServer/Web/DownloadIssueDocument.ashx. The code in creates a hyperlink with a relative URL that uses the syntax .. to refer to the parent folder. If the download link doesn’t work when you deploy your application, you should check that you’ve deployed your DownloadIssueDocument.ashx file to the expected location. Figure 8-46 shows how your issue document dialog now looks at runtime.

You might wonder why you’ve added this code to the postRender method rather than create a custom control that’s based on the IssueDocument Id. One of the reasons is because the HTML client applies the read-only and disabled properties of your content item when it renders custom controls (Figure 8-47). When the HTML client applies the disabled and read-only renderings to a custom control that includes a hyperlink, it makes the hyperlink nonclickable. You can’t set the Id property of an entity to not be read only, so the simplest workaround is to append the custom HTML in the postRender method rather than use a custom control. Therefore, if you create a custom control and it doesn’t work as you would expect it to work, it’s worth checking these rendering options.

Applying Themes

The HTML client uses jQuery mobile controls and, because of this, you can apply jQuery mobile themes to your application. The advantage of using a theme is that it allows you to package the appearance of your application in a single file. You can easily use the same theme in multiple applications, and even share your themes with other developers. A quick search for “jQuery mobile themes” on the Internet will reveal lots of themes that you can download and use.

By default, the HTML client applies a theme that uses a white background. However, it also includes a theme that consists of a black background with white text. When you’re developing mobile applications, it’s good practice to use the “dark theme” with a black background because it decreases the drain on the battery. This is because it minimizes the screen area that the device needs to light up.

LightSwitch stores its themes in the Content folder of your HTMLClient project. This folder also contains additional CSS files that define the appearance of your application. These files are shown in Figure 8-48.

The CSS files that contain the dark and light themes are called dark-theme.css and light-theme.css, respectively. To set up your application so that it uses the dark theme, open your default.htm file. You’ll find this in the root folder of your HTMLClient project.

Near the top of this file, you’ll find two style-sheet links that point to the light-theme.css and msls-light.css files. To use the dark theme, modify these links so that they point to the dark-theme.css and msls-dark.css files instead.

When you now run your application, LightSwitch applies a black background rather than a white background. If your application still shows a white background, it’s likely that your browser has cached your default.htm file. You can fix this by problem by clearing your browser cache.

Creating Your Own Themes

The jQuery web site provides a tool called Theme Roller (Figure 8-49) that makes it very easy for you to create custom themes. To use Theme Roller, open your web browser and navigate to http://jquerymobile.com/themeroller/.

You can simplify the process of creating a theme by taking the light theme as a starting point for further customization. On the Theme Roller web site, click on the Import button that appears toward the top of the page. This opens a dialog that allows you enter a theme. Open your light-theme.css file, and copy and paste the contents into this dialog.

Once you’ve imported your theme, you can use the graphical designer to customize your theme. When you finish making your modifications, you can download your theme by clicking on the download button that appears at the top of the page. The download button creates a zip file that contains the CSS file for your theme. Extract the CSS file into your HTML client project’s Content folder, and modify your default.htm file so that it points to your new theme file.

Changing the Application Icon and Title

The HTML client shows an icon that contains a mixture of blue squares while your application loads. Once your application loads, it shows a similar icon in the top left part of your home screen and sets the browser tab or window title to “<ProjectName>.HTMLClient” (Figure 8-50).

The title tag in your default.htm file defines your page title. You can change this from “<ProjectName>.HTMLClient” to something more meaningful by modifying the value of the title tag. Near the top of the default.htm file, you’ll find a div tag that contains the value “<ProjectName>.HTMLClient.” This is the text that LightSwitch shows in the lower part of the screen when your application loads. Once again, you can modify this to a value that better describes your application.

The HTML client stores the home page and splash-screen images in the folder HTMLClientContentImages. The home page image is called user-logo.png, and the splash screen image is user-splash-screen.png. To use different images, you can replace these two files with new images.

Securing Methods

Each screen method that you create allows you to add JavaScript to a CanExecute method. Figure 8-52 shows the “Edit CanExecute Code” link that appears in the properties sheet for a method. You can prevent users from calling this method by setting the return value of the CanExecute method to false.  

In Chapter 17, you’ll discover that LightSwitch includes a security model that allows you to define permissions. The advantage of this system is that it allows you to apply access control at a granular level.

Unfortunately, LightSwitch’s JavaScript API doesn’t include the methods that allow you to determine whether the logged-in user has been granted a certain permission. This means, for example, that you can’t easily restrict access to screens for editing and deleting engineers to only those users that you define as “managers.”

If you need to apply access control based on group membership, a possible (but not ideal) workaround is to create separate applications for each group of users. Another option is to build your own authorization mechanism that ties into your CanExecute methods. If you choose to do this, it’s important to remember that JavaScript is a text-based, uncompiled language that runs on the client. Because of this, users can easily view the source of your application and work out ways to compromise any custom security code that you’ve written.

Looking at the wider picture, the best place to implement security code is on the server. In Chapter 17, you’ll learn how to prevent users from accessing or updating data by implementing access-control checks through the server and query pipelines. To help you apply server-side access control, LightSwitch allows you to obtain the logged-in user through server-side code, after you’ve enabled authentication in your application.