May 20

Written by: Michael Washington
5/20/2013 9:31 PM 

You can easily implement animated help agents in your Visual Studio LightSwitch HTML Client applications.

ClippyJS is a library by Smore.com, that is a JavaScript implementation of Microsoft Agents.

In this article we will combine the Creating a wizard-like experience for HTML client application by Andy Kung with ClippyJS.

Set-up

The first step is to download the ClippyJS code and unzip the file.

In the Visual Studio Solution Explorer, switch to File View.

Right-click on the Content folder and select Add / Existing Item.

 

Add the clippy.css to the Content folder and the Clippy.js and clippy.min.js to the Scripts folder.

Add references to the clippy.css  and the clippy.min.js to the default.htm page.

 

Add Clippy to the Page

To add Clippy to the page, we open the screen designer and open Write Code, and select the created method.

We use the following code for the method:

 

var Clippy;
myapp.SurveyList.created = function (screen) {
    clippy.load('Clippy', function (agent) {
        // Set Clippy
        Clippy = agent;
        // Show Clippy
        Clippy.show();
        Clippy.speak('I see you are using a Lightswitch app, I am here to help!');
    });
};

 

When we run the application, Clippy shows and he speaks!

 

Using Clippy on Multiple Pages

It is important to understand that LightSwitch creates Single Page Applications (SPA). Because of that we only want to load Clippy once. However, when we navigate to subsequent pages, we will see Clippy, but we will not have programmatic reference to him.

To resolve this, we can pass a reference to Clippy to the next page.

The first step is to open the page we need to show Clippy on next, and create a property to receive Clippy.

We click Add Data Item, select Local Property, select Binary, name the property Clippy and click OK.

The property will show in the View Model for the page. We do not want or need to drag and drop the property to the page.

To pass Clippy to the next page, we open the page that we want to send Clippy from, and create a button, and select Edit Execute Code for the button’s action.

We use the following code for the button:

 

myapp.SurveyList.AddSurvey_Tap_execute = function (screen) {
    // Stop Clippy
    Clippy.stop();
    // Open the New Survey
    myapp.showNewSurvey(null, {
        beforeShown: function (newSurveyScreen) {
            // Pass Clippy to the new screen
            newSurveyScreen.Clippy = Clippy;
            // Create new Survey here
            var newSurvey = new myapp.Survey();
            newSurveyScreen.Survey = newSurvey;
        }
    });
};

 

On the receiving page, we open the screen in the screen designer, then select Write Code then the created method.

We use the following code:

 

myapp.NewSurvey.created = function (screen) {
    Clippy.speak('Lets get started!');
};

 

When we run the application and navigate to the page, we see that Clippy is hidden under the tool bar!

We alter the method to the following code:

 

myapp.NewSurvey.created = function (screen) {
    // Move Clippy so he is not hidden by the toolbar
    var HTMLPageheight = $(document).height();
    var HTMLPagewidth = $(document).width();
    Clippy.moveTo(HTMLPagewidth - 250, HTMLPageheight - 200);
    Clippy.speak('Lets get started!');
};

 

Now, Clippy has plenty of room.

 

Using Binding

We can have Clippy react instantly when anything on the page is changed.

We can select a control that is bound to a value, and then select Edit PostRender Code.

We use the following code:

 

myapp.NewSurvey.Name_postRender = function (element, contentItem) {
    // Binding to only the Name property
    contentItem.dataBind("value", function (newValue) {
        if ((newValue != null) && (newValue != undefined)) {
            Clippy.speak('Hello ' + newValue + '!');
        }
    });
};

 

When we run the application, Clippy will react when we enter our name and tab away from the field.

We can also use code such as this to have Clippy speak when it is appropriate:

 

    // Go to next step only if there are no validation errors associated with the field. 
    var contentItem = screen.findContentItem("Name");
    if (contentItem.validationResults.length === 0) {
        screen.showTab("Step2");
        screen.details.displayName = "Step 2";
        Clippy.speak('So ' + screen.Survey.Name + ' tell me your Quest!');
    }

 

 

 

Special Thanks

A special thanks to LightSwitch Team member Andy Kung.

 

Download Code

The LightSwitch project is available at http://lightswitchhelpwebsite.com/Downloads.aspx

(you must have Visual Studio 2012 Update 2 installed to run the code)