Enhancing LightSwitch Controls with jQuery Mobile (Michael Zlatkovsky)

myapp.CustomerDetail.FamilySize_render = function (element, contentItem) {// Write code here.};

) that the custom control can write to, while “contentItem” represents view-model information about the item. Thus, we’ll use “element” for where to place the custom control, and “contentItem” for what it represents.

Let’s start with a simple question: assuming you did have a custom control that magically did all the work for you, what parameters would you need to pass to it? Obviously, “element” and “contentItem” from above are necessary. We’d also need to know the minimum and maximum values for the slider… and that’s about it.

A slider control seems like a reasonably generic component, so instead of writing all of the code in this one function, it might be worth separating the generic slider logic from the specifics of this particular instance. Thus, our function above can become:

myapp.CustomerDetail.FamilySize_render = function (element, contentItem) {// Write code here.createSlider(element, contentItem, 0, 15);
};

Well, that was easy! But now, let’s actually implement the hypothetical “createSlider” function.

Rendering a Slider

The first thing our createSlider function needs to do is create the necessary DOM element. jQueryMobile’s Slider documentation tells us that the Slider operates over a typical tag. So a reasonably first attempt would be to do this:

function createSlider(element, contentItem, min, max) {// Generate the input element.$(element).append('+ min +'" max="' + max + '" value="' + contentItem.value + '" />');
}

On F5, you will see that the field indeed renders as a slider. Mission accomplished?

Unfortunately, not quite. If you drag another FamilySize element to the screen (just so you have a regular text box to compare to), you’ll see that the input slider does not seem to do anything. You can drag the slider up and down, yet the other textbox does not reflect your changes. Similarly, you can type a number into the other textbox and tab out, yet the slider is not impacted.

What you need to do is create a binding between contentItem and the slider control. To do this, you’ll actually create two separate one-way bindings: one from contentItem to the slider, and one from the slider to contentItem. Assume for a moment you already have a $slider object, bound to an already-created jQueryMobile slider. The code you would write would be as follows:

 

// If the content item changes (perhaps due to another control being
//     bound to the same content item, or if a change occurs programmatically), 
//     update the visual representation of the slider:contentItem.dataBind('value', function (newValue) {
    $slider.val(newValue);
});// Conversely, whenever the user adjusts the slider visually,
//     update the underlying content item:$slider.change(function () {
    contentItem.value = $slider.val();
});

How do you get the $slider object? The simplest way is to let jQueryMobile do its usual post-processing, but this post-processing happens after the render functions have already executed. The easiest approach is to wrap this latter bit of code in a setTimeout call, which will execute after jQueryMobile’s post-processing gets executed. See Joe’s Custom Controls post for another case – performing actions against a “live” DOM – where you may want to use setTimeout.

Putting it all together, the final createSlider code is:

function createSlider(element, contentItem, min, max) {// Generate the input element.$(element).append('+ min +'" max="' + max + '" value="' + contentItem.value + '" />');// Now, after jQueryMobile has had a chance to process the 
    //     new DOM addition, perform our own post-processing:setTimeout(function () {var $slider = $('input', $(element));// If the content item changes (perhaps due to another control being
        //     bound to the same content item, or if a change occurs programmatically), 
        //     update the visual representation of the slider:contentItem.dataBind('value', function (newValue) {
            $slider.val(newValue);
        });// Conversely, whenever the user adjusts the slider visually,
        //     update the underlying content item:$slider.change(function () {
            contentItem.value = $slider.val();
        });
    }, 0);
}

When you F5, you’ll see that both Family Size controls – the textbox and the custom slider – stay in sync. Success!

Creating a Flip Switch for a Boolean field

Having created the Slider, let’s create another control for the Boolean field of “Active Subscription”. Just as with the Slider control, jQueryMobile offers a great Flip Toggle Switch (with customizable labels, if you’d like):

As with the “Family Size” field, we can go to the Active Subscription’s properties and switch it from a Text Box to a Custom Control. I will also change the width to “Stretch to Container”, change the Display Name to just “Subscription”, and finally click “Edit Render Code”:

myapp.CustomerDetail.ActiveSubscription_render = function (element, contentItem) {// Write code here.};

As before, let’s encapsulate the main functionality in a function, that we’ll call from the ActiveSubscription_render method. The information we want to pass in is similar to the Slider. We’ll need “element” and “contentItem”, and we’ll need the analog of a “min” and “max”: in this case, the labels for the true and false states. Reading over the Flip Toggle Switch documentation, we’ll also notice that width must be set explicitly in case for non-standard on/off labels. Thus, we’ll pass in a width parameter as well.

myapp.CustomerDetail.ActiveSubscription_render = function (element, contentItem) {// Write code here.createBooleanSwitch(element, contentItem, 'Active', 'Inactive', '15em');
};

Now for the fun part – the createBooleanSwitch function. Conceptually, the function is very similar to createSlider.

First we initialize the DOM:

var $selectElement = $('').appendTo($(element));
    $('' + falseText + '').appendTo($selectElement);
    $('' + trueText + '').appendTo($selectElement);

Then, inside a setTimeout (which allows us to operate with the jQuery object for the flip switch), we:

1. Set the initial value of the flip switch (we did this in the DOM for the slider, but it’s a little trickier with the flip switch, so I’ve encapsulated it into a shared function that’s used both during initialization and on updating)

2. Bind contentItem’s changes to the flip switch control

3. Bind the flip switch’s changes back to the contentItem

4. One additional step, which we didn’t need to do for the slider: explicitly set the flip switch’s width, as per the documentation.

The resulting createBooleanSwitch code is as follows:

function createBooleanSwitch(element, contentItem, trueText, falseText, optionalWidth) {var $selectElement = $('').appendTo($(element));
    $('' + falseText + '').appendTo($selectElement);
    $('' + trueText + '').appendTo($selectElement);// Now, after jQueryMobile has had a chance to process the 
    //     new DOM addition, perform our own post-processing:setTimeout(function () {var $flipSwitch = $('select', $(element));// Set the initial value (using helper function below):setFlipSwitchValue(contentItem.value);// If the content item changes (perhaps due to another control being
        //     bound to the same content item, or if a change occurs programmatically), 
        //     update the visual representation of the control:contentItem.dataBind('value', setFlipSwitchValue);// Conversely, whenver the user adjusts the flip-switch visually,
        //     update the underlying content item:$flipSwitch.change(function () {
            contentItem.value = ($flipSwitch.val() === 'true');
        });// To set the width of the slider to something different than the default,
        //    need to adjust the *generated* div that gets created right next to
        //    the original select element.  DOM Explorer (F12 tools) is a big help here.if (optionalWidth != null) {
            $('.ui-slider-switch', $(element)).css('width', optionalWidth);
        }//===============================================================//

        // Helper function to set the value of the flip-switch
        //     (used both during initialization, and for data-binding)
        function setFlipSwitchValue(value) {
            $flipSwitch.val((value) ? 'true' : 'false');// Because the flip switch has no concept of a "null" value
            //    (or anything other than true/false), ensure that the 
            //    contentItem's value is in sync with the visual representationcontentItem.value = ($flipSwitch.val() === 'true');
        }
    }, 0);
}

On F5, we see that our control works. Again, I put in a dummy textbox for “Active Subscription” to show that changes made in one field automatically get propagated to the other. You’ll notice that on initial load, the text field is set to “false”, rather than empty, as before. This is because of the flip switch has no concept of a “null” value, so I explicitly synchronize contentItem to the flip switch’s visual representation in the setFlipSwitchValue function above.

Removing the temporary “Active Subscription”, we get to this final result:

Next Steps:

Hopefully, this post whets you appetite for what you can do with Custom Controls in the LightSwitch HTML Client, and gives you a clear sense on how to wrap arbitrary controls into LightSwitch-usable components. Leave a comment if you have any questions, and, once again, thank you for trying out Preview 2!

- Michael Zlatkovsky, Program Manager