Tuesday, January 8, 2013

WebSDK: Olark Web Widget - Part 2 - Events

Welcome to Part 2 of this tutorial on converting the Olark notification widget into a Web control for use with Real Studio! If you haven't read Part 1, I suggest you do so because we'll be building on the project from last time.


Now that we have a control that works, we're going to hook up some of the basic events that are available. As of this writing there are only ten of which we will be hooking up four: Expand, Shrink, Show and Hide.

First, let's prepare the class for receiving events from the page:

Add four event definitions, one for each event. These will be the events that your user implements at design time.



Notice that we duplicated the Hidden and Shown events. We're going to override the behavior of these events to reflect the events from the widget instead of the web control instance itself. Since we want to be able to raise those events from code, we need a new event definition.

Because we've created a duplicate Hidden event and there's already an unimplemented event named Hidden that we're not going to use, the compiler will complain if you try to build right now. In the Hidden event of the control, simply add a comment like this:

//These are not the droids you are looking for...

Now that we have the events, we need to add some code to fire them when an event comes in from the browser. Go to the ExecuteEvent event and add the following code:

Select Case Name
Case "oExpand"
  RaiseEvent Expanded

Case "oCollapse"
  RaiseEvent Collapsed

Case "oShow"
  RaiseEvent Shown

Case "oHide"
  RaiseEvent Hidden

Case Else
  Return False

End Select

Return True

So you're probably wondering why I prefixed each of the incoming event names with "o". The reason is simple...to avoid a conflict with the existing Show and Hide events for the control! I also used shortened names because every byte that you send from the browser takes time. Not a lot of time, but it does add up, and for most mobile users that have data plans, every byte costs money!

Now that we have the infrastructure in place, we can tell the browser to listen for the events. Before we do that though, lets talk a little more about bandwidth. As I mentioned above, when designing controls, bandwidth should be foremost on your mind. One area that developers often forget about is the fact that some events may not be implemented by users at all. Sending event data from the browser in this case is an outright waste! We'll use the EventIsImplemented method to check at runtime whether or not there's actually code in an event. Back to the tutorial!

In the Shown event, we'll tell the browser to listen for the Olark events as specified in the Olark API:

If EventIsImplemented(GetTypeInfo(OlarkWidget), "Expanded") Then
ExecuteJavascript("olark('api.box.onExpand', " + _
  "function() { RS.triggerServerEvent('" + Self.ControlID + _
  "','oExpand', [] ) } )")
End If

If EventIsImplemented(GetTypeInfo(OlarkWidget), "Collapsed") Then
ExecuteJavascript("olark('api.box.onShrink', " + _
  "function() { RS.triggerServerEvent('" + Self.ControlID + _
  "','oCollapse', [] ) } )")
End If

If EventIsImplemented(GetTypeInfo(OlarkWidget), "Shown") Then
ExecuteJavascript("olark('api.box.onShow', " + _
  "function() { RS.triggerServerEvent('" + Self.ControlID + _
  "','oShow', [] ) } )")
End If

If EventIsImplemented(GetTypeInfo(OlarkWidget), "Hidden") Then
ExecuteJavascript("olark('api.box.onHide', " + _
  "function() { RS.triggerServerEvent('" + Self.ControlID + _
  "','oHide', [] ) } )")
End If

Now go to WebPage1, add a WebListBox to the page and add this code to each of the new events:

Listbox1.InsertRow 0,CurrentMethodName

This listbox is simply for testing purposes to allow us to see that each of the events is firing when we want it to.

Save and Run the project! The Shown event should fire fairly soon after the page loads, and the Expanded and Collapsed events should fire as the user expands, shrinks or closes the control (if the theme1 has a close control).

We've come a long way, but the Olark API still has a lot of configurability available through properties and methods.

Next time we'll look at some methods that trigger the behavior whose events we've implemented today.

1) The theme of the Olark widget is determined by settings in your Olark account.

No comments: