Thursday, January 10, 2013

WebSDK: Olark Web Widget - Part 4 - Setting Properties

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


Width, Height and Visible Properties

By default, the Olark widget appears in the lower right corner of the browser window and has a size of 300x300 pixels. This works as long as there is nothing about your site that would be obscured in this position. Today we are going to set up some of the properties that allow you to change the initial appearance.

Because we have set this control to appear in the tray, the width and height properties are technically unused. Lets override their behavior for our purpose. We will also be overriding the Visible property to set the initial and runtime visibility of the widget.


First of all, the Olark API has two different methods for setting properties – one for setting properties at runtime and one for setting them before the control loads. The initial visibility, and the Width and Height need to be set as part of the configuration before the control loads so we need to set them as the library is loaded in the SetupJavascriptFramework event. Lets make a few changes:



dim c as string = code.ReplaceAll("<<SiteID>>",Trim(SiteID))

if not Visible then
  c = c + "olark.configure('box.start_hidden', true);"
end if

c = c + "olark.configure('box.width','" + str(width,"0") + "');"
c = c + "olark.configure('box.height','" + str(height,"0") + "');"

return c

Note: The Width and Height don't work with all themes.

In the FrameworkPropertyChanged event, let's add some code to intercept changes to the visibility property:



Select Case Name
  Case "visible"
    if ControlAvailableInBrowser then
      if value then
        ExecuteJavascript("olark('api.box.show');")
      else
        ExecuteJavascript("olark('api.box.hide');")
      end if
    end if

End Select

In the Shown event, we need to add a bit of code to set the initial hidden state, after the 4 EventIsImplemented calls:


if not Visible then
  ExecuteJavascript("olark('api.box.hide');")
end if


Position
Lastly, there is a property that can be used to set the initial position of the widget on the browser window named box.corner_position. Lets set that property up now.

1. Add a property to your control:



Position as Integer

2. Right-click on the property and select Property List Behavior.
3. Click the checkbox next to the Position property to make it visible in the IDE.
4. To make it a little easier to understand in the IDE,  we'll use an enum to set the value. Under Enumerations, change the popupmenu from None to Custom.
5. Create 4 entries:


0 = Bottom Right
1 = Bottom Left
2 = Top Right
3 = Top Left

6. Set the default value to 0.
7. Click OK.

Now let's add the code to the SetupJavascriptFramework event:


Add the code in red to the event: 




dim c as string = code.ReplaceAll("<<SiteID>>",Trim(SiteID))

if not Visible then
  c = c + "olark.configure('box.start_hidden', true);"
end if

c = c + "olark.configure('box.width','" + str(width,"0") + "');"
c = c + "olark.configure('box.height','" + str(height,"0") + "');"

dim positions as String = "BR,BL,TR,TL"
c = c + "olark.configure('box.corner_position','" + _
  NthField(positions,",",position+1) + "');"

return c

Note: Like the Width and Height properties, not all of the box position values are supported with all themes. The holiday theme (the one with the Santa hat) only works in the Bottom Left and Bottom Right positions. You can change the theme of your Olark widget from your control panel at Olark.com.

Now when a developer wants to change the position of the Olark widget, they can simply choose the descriptive name of the position.


Phew! There's a lot going on there! Our control is almost complete. Next time we will be making it so this control will stay visible even if your user changes pages, but also make it possible to keep receiving the events!

No comments: