Monday, January 7, 2013

WebSDK: Olark Web Widget - Part 1 - Getting Started

It seems like every day I'm getting questions about how to convert this or that to a web control using the new WebSDK. Over the next five days, I'll walk you through the process of creating an Olark web live chat widget. Today's post is all about getting the widget to appear in your project.


First of all, if you don't already have one, go to the Olark website and sign up for a free account. After you sign in, they will provide you with a piece of javascript code and a Site ID. I suggest copying each of these to the text editor of your choice. It is probably worth having the API documentation open in a browser as well: Whenever converting a control, it is extremely important that you spend a little time familiarizing yourself with the API and the examples provided.

In preparation for creating the control, look at the javascript that you just copied. You'll notice that the SiteID that was provided for you exists in several places in the code. If you leave it this way, anyone who uses this control will use your account (and their tech support chats will likely come to you!). Lets fix that. Copy the SiteID into your clipboard and do a search & replace on the javascript code. Change all instances of the SiteID on the clipboard (looks something like 0000-000-00-000) to <<SiteID>>.

The last piece of the prep stage requires that you think ahead a little. We'll be sending this code to the browser as part of the SetupJavascriptFramework event. This event expects you to return raw Javascript code with no <script> tags around it. If you look at the provided code, not only does it contain a <script> tag, but there is also a <noscript> tag. Remove everything up to and including the first <script> tag (and its attributes) as well as everything from the </script> tag to the end of the script (including the whole <noscript> section and the trailing comment).

Creating the Widget

Next, launch Real Studio 2012r2 and create a new Web project.
  1. Create a new class called OlarkWidget with the Super set to WebControlWrapper
  2. Open the OlarkWidget class and add a constant to specify the control's javascript namespace. Replace "example" with your own namespace. If you haven't registered a namespace with us, please see the excerpt from the WebSDK docs at the end of this article, for information about doing that.
    Private Const JavascriptNamespace as String = "example.olark"
  3. Add a second constant to make the control appear in the tray instead of on the page:
    Private Const ShowInTrayArea As Boolean = True
  4. Add a third constant for the javascript code, and paste in the javascript code we prepared above:
    Private Const Code As String
  5. Add a SiteID property so users can set it in the IDE at design time:
    Public Property SiteID as String
  6. Implement the SetupJavascriptFramework event. Notice that we're inserting the user supplied SiteID.
    Return Code.ReplaceAll("<<SiteID>>",Trim(SiteID))
  7. Lastly, right-click on the SiteID property and select Property List Behavior. In this dialog, set the Width and Height default values to 32 (otherwise it'll look a little weird when you drag the control in) and check the box next to the SiteID property to make it visible in the WebPage editor. You can add a header by right-clicking in the property list and choosing "Add Header".

Using the Widget

Now go to WebPage1 and drag an instance of OlarkWidget to the page. It should automatically appear in the tray and if you select it, you'll notice that the SiteID property is visible. Copy and paste your SiteID into that field.

If you run the project, soon after the page loads, the default Olark widget should appear on the bottom right corner of the browser!

Next time we'll hook up some basic events!

How to Register a Javascript Namespace

Real Software is maintaining a Javascript namespace registry to help developers avoid namespace conflicts.  Developers may register a root namespace for use with all of their controls. Using the examples above, the registered namespace would be “Acme”. From then on, you would be permitted to create:
  • Acme.Button
  • Acme.Listbox
  • Acme.SourceList
This does NOT permit you to use AcmeControls or AcmeProducts without creating a separate namespace registration.
To request a root namespace registration, send an email to and tell us what root namespace you would like to use. You will receive an email from us confirming your namespace choice. 
Namespaces will be registered on a first come first served basis. We reserve the right to deny a namespace request that infringes on the trademarks of another company or would be otherwise confusing or offensive.

1 comment:

Jay said...

I get an error in the browser:

Could not execute returned javascript: Unexpected token '<'
Source: var langdir = document.getElementsByTagName('body')[0]; if(langdir) { langdir.removeAttribute('dir'); }
var langdir = document.getElementsByTagName('body')[0]; if(langdir) { langdir.setAttribute('lang','en-us'); }

(The comments wont let me past the javascript from Olark here.....