3. Advanced SDK Concepts

Now that you’ve got a basic understanding of how to use the Genie JavaScript SDK, let’s move on to some more advanced concepts that the SDK supports.

Adapters

Although the Genie JavaScript SDK provides basic UI functionality out of the box, its core purpose is to facilitate communication with the server. When building rich web applications, you will typically want to make use of a third party UI library. There are many of these available, and you should choose the one that best suits your needs. The SDK doesn’t want to dictate which one you should use, and thus has been designed to be extensible, providing the hooks to allow you to plug a third party UI library in. You can plug third party UI libraries into the Genie JavaScript SDK using adapters.

Adapters are designed to bridge the gap between the SDK’s built in controls and third party UI controls – effectively connecting them together.  For example, an adapter might be used to connect a third party date picker control to the SDK’s FieldView control.

Typically, an adapter will work like this:

• When the web page has finished loading, it will search all the elements on the page for those with a given attribute name and value indicating that that adapter should be used on this element (e.g. adapter="datepicker").
• When an element matching its criteria has been found, it will listen for events that it’s interested in (which will be raised on the element by the Genie SDK as data is received from the server, etc).  It may also choose to insert a third party control as a child of the element.
• When one of these events is raised, it will respond accordingly.  For example, it may translate the messages/data received from the Genie SDK, and manipulate the third party control accordingly.

Rather than providing a bridge between the Genie SDK and a third party control, some adapters may simply extend or customise the behaviour of the Genie SDK’s controls.  For example, the SDK provides a time input adapter, which manipulates what value from the data returned from the server is to be displayed by the Genie SDK’s FieldView control.  There is also a breadcrumb adapter, which hooks into a data control, and takes control of its rendering. 

Instead of listening for events to be raised by the built in SDK controls, some adapters completely override specific functions within the SDK’s controls, replacing an existing implementation with their own.  This technique is primarily used when the control being adapted hasn’t been explicitly declared in the HTML of a page (therefore an adapter to use can’t be specified by the user), or when all uses of a control should be adapted (with no opt-in/out requirement on the part of the developer, and there’s no per-instance configuration required).  For example, the KendoUI adapters automatically hook into the ContextMenuView control and handle the rendering of all context menus displayed by the application.

As you can see, adapters demonstrate how extensible the Genie JavaScript SDK is.

Out of the box, the Genie JavaScript SDK provides support for some of the controls in the third party KendoUI library, provided by Telerik.  These adapters include:

• kendoComboBox
• kendoDatePicker
• kendoDropDownList
• kendoFileUpload
• kendoMobileListView
• kendoPanelBar
• kendoWindow
• kendoTabStrip
• kendoTimePicker
• kendoTreeView

These adapters will be detailed further later in this document.  If you’re not using KendoUI, you can use these as examples for creating your own adapters for your chosen UI library.

To use the KendoUI adapters, you need to:

1. Add the script references to the top of the page for the adapters you want to use. Note that kendoAdapter.js is a required file reference.
2. For each element that you want an adapter to render, set its adapter attribute to the value that the adapter will search for. For example, here are two fields that use the KendoUI date picker and KendoUI drop down list adapters, respectively:

<input id="EventDate" attribute='value' adapter="datepicker" />
 
<div class='' bind="datafield" fieldid="myField" populatemethod="myMethod">
    <input id="myList" adapter="dropdownlist" emptyitemlabel="Select a Value" />
</div>

Creating Your Own Adapters

You can easily create your own custom adapters.  Once the page has loaded (i.e. the document is ready), adapters typically search for elements with a given attribute value specified, and customise those elements according to their requirements. The adapter can listen for events on those elements (the SDK will fire events on them), and respond accordingly.

The TimeInputAdapter is a simple example of how to implement a custom adapter, which listens for the valueUpdated event on an element (triggered by the SDK), and renders an alternative attribute value than the value attribute returned from the server.

Using the Custom Content Control

The server can publish data within a CustomContent element.  This enables data of any format and structure (as determined by the server application) to be published to the client.  For example, data used to populate a Google Map may be sent to the client this way.  The SDK doesn’t know how to render this data, so it leaves it up to the client application to handle this, by raising an event that can initiate the rendering when data has been received.

To start with, create a div, assign the id of the custom content element that it will map to on the server to its customcontentid or id attribute, and set its bind attribute to “customcontent”, like so:

<div id="MyCustomContent" bind="customcontent"></div>

A customcontent:contentpublished event will be raised on this div whenever a custom content element with an ID matching the value of the customcontentid/id attribute is received from the server.  It is then up to your client application to listen for this event and render the data accordingly.  For example, the following code listens for the event and extracts the XML content, ready to render:

$("MyCustomContent").bind("customcontent:contentpublished", function (event, model) {
    var $xml = model.$rawXml;
    // TODO: Parse the xml and render the data to the screen
});

Note: If you expect to be reusing the same functionality elsewhere, consider wrapping the XML parsing and rendering in an adapter.

Customising HTML Generated by the SDK

The SDK generates some HTML dynamically to implement various scenarios, such as a loading indicator to indicate to the user that it’s waiting for a response from the server.  If you don’t like the default implementation, you can specify your own elements to be used instead.  Essentially, this just involves rewriting the functions under the genie.html namespace (found in the genie.html.js file in the source).  Each function returns an element wrapped in jQuery, which the function caller can append to the DOM.  You can rewrite various functions and return your own element to be used in place of the SDK’s implementation.

Pop Up Login Window

Provide an alternate implementation of the pop up login window by rewriting the genie.html.popupLoginForm function.

Overlays

Provide an alternate implementation of the pop up login window by rewriting the genie.html.overlayElement function.

Note that the root element must be named "overlayEx", that is it must have an id="overlayEx" attribute.

Loading Indicator

Provide an alternate implementation of the pop up login window by rewriting the genie.html.loadingIndicator function.

Note that the root element must be named "loadingIndicatorEx", that is it must have an id="loadingIndicatorEx" attribute.

Pop Up Windows as Activity Containers

When an activity is requested, you may wish to pop up a window and use that as the activity container. However, the SDK only has partial support for popup windows, so the responsibility of displaying and managing a popup window will need to be that of a third party UI library. The SDK provides a KendoUI adapter for the kendoWindow control (in KendoPopupWindowAdapter.js), so if you’re using KendoUI then support for popup windows is included “out of the box”. If you’re using another UI library, then you’ll need to create a custom adapter for it, which you can base upon the existing KendoUI adapter.

Let’s assume for now that you’re using KendoUI in your application, and host an activity in a popup window:

1. The first step is to create a HTML page on the server whose content will appear in the popup window. This page should include a div that will bind to an activity, and the field and method bindings required by the activity. Note that you don’t need to include the script references at the top of the page.
2. Now that you have a page, you need a form mapping for it. This is much like the form mappings that we’ve created earlier, but:
   1. the form attribute will need to point to the full path on the server of the HTML page you just created
   2. you’ll need to add a onRequest="popup" to the mapping, and
   3. you can specify a title to show in the window’s caption bar using the title attribute.

<activity form="ContentPages/MyPopupActivity.html" name="[activityname]" style="[activitystyle]" onRequest="popup" title="My Popup Title" />

Now when the server requests the activity, the SDK will pop up a window on the current page and display the activity in it.

Loading Partial Content from the Server

Like My Details gets individual tab content.  Set autoLoad=”false” on activity.  Use code to load activity when content loaded.  See KendoTabStripAdapter.

genie.factory.bindActivities($(e.item).parents(), true);

Creating Custom Templates for Use with the Data Publication Control

TODO

The data publication control has been designed such that you can override its default rendering templates with your own.

sortField

defaultSortDirection (asc/desc)

Note that header templates for tables should include the <thead> element.

Pick Lists

Support for pick lists has been provided, but since they need to appear in a popup window, they (like popup window activity containers) need a UI library to provide the popup windowing support, via an adapter.

Debugging the Server Communication

If you want to debug the requests being made to the server, and the responses being returned, you can simply open the console in your browser’s debugging tools (Firebug for Firefox, Chrome Developer Tools for Chrome, IE Developer Tools for IE, etc).  All requests and responses will be written there.

Unfortunately, the XML will not be laid out in an easily readable fashion (all elements are on one line), so you’ll probably need to copy it and paste it into an XML file in Visual Studio or other tool that will format XML to be able read it.

Debugging the SDK Source

The “Configuring the Required JavaScript References” section earlier in this document demonstrated a way to selectively reference the SDK’s source files when running in debug mode, and the bundled and minified files when running in release mode.

Note: The mode is configured in the Web.config file.

If you have a released website that uses the bundled and minified version of the SDK, and you need to debug it, we provide source maps (*.map files) that you can use to map the “compiled” SDK back to its source. More information on source maps can be found here: http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/

Communicating with Anonymous Activities

TODO

Message Transformation

The message control will display messages from the server, but the text from these messages is not always “user friendly”, and sometimes you might want to support custom localisation of the messages. The SDK contains support for transforming these messages to something more suitable (or suppress certain messages completely), via the jquery.i18n.properties library.

You can turn off message transformation by setting the genie.config.useBundle variable to false.

The SDK expects a file named Messages.properties under the server path specified by the messageBundlePath property on the window.config object that we configured earlier in this document (by default the assets folder). This file should specify a set of key/value pairs, like so:

key=value

The key needs to match the message key returned from the server, and the value should be the message that you want to actually display to the user.

For messages that you want to transform, but don’t have an associated key returned from the server, you can hook into the pipeline and transform a message string to a key in JavaScript before it is transformed. To do so, implement the window.genie.findMessageKey function in a custom JavaScript file, and have it return a key based upon the message passed into it:

window.genie.findMessageKey = function (messageText) {
    if (messageText === "message1" {
        return "key1";
    } else if (messageText === "message2" {
        return "key2";
    } //etc
}

This key will then be fed into the pipeline, and transformed to the message with that key from the Messages.properties file.

Note: You can suppress messages by specifying no value for the given key. Messages with no value will not appear in the message control.

Components

Not recommended for use

Maintenance Page

The SDK periodically checks to see if the application server is still alive. It does so by sending a “ping” message to the proxy, which tells it if the server is alive or not. If it’s not, then it will redirect the user to a page that can state that the server is under maintenance, and that the application cannot be used currently. The name of this page is configured in the config.js file we implemented earlier in the document. We also set up a page (Maintenance.cshtml) and an action for it. Therefore, all you need to do is to put the required text on the page informing the user that the application server is not currently available.

Listening for Field Value Changes in your Custom JavaScript

TODO