Javascript library

iKnowBase provides a javascript-library in the client page. For the most part, the content of this is private for the various components. However, for components in the page engine there is one feature that might be useful.

The objects, methods and properties in the iKnowBase javascript library are generally not intended for manual use, and they will change between versions. However, as far as possible, the items specified in this document will remain backwards compatible.

Global objects

These are the global (top level) objects available to HTML clients, provided automatically by iKnowBase.

iKnowBase root object

This object contains functions and properties relating to the entire iKnowBase application.

busyIndicator

The busyIndicator method on the iKnowBase-object will run the given function and show a busy indicator while the function runs. It can apply to either a whole page or a given component.

Parameters

The hash parameter supports the following properties:

Methods

Example

The following function will show the busy indicator while loading css and scripts. It is manually closed in the start-function’s callback.

IKB.ensure = function(data, callback) {
    iKnowBase.busyIndicator({autoClose: false, start: function() {
        var busy = this;
        load($.makeArray(data.js), $.makeArray(data.css), data.wait, function() {
            busy.close();
            callback();
        });
    }});
}

notify

The notify method on the iKnowBase-object will show a notification to the user. It can be of type error, warning, or information. The notification will close when the user clicks on it.

Parameters

The hash parameter supports the following properties:

Methods

Example

The following code will show a notification of type information to the user. It will close automatically after 3 seconds.

iKnowBase.notify({
    type:'info',
	  title:'Shows both info-icon, title, and text',
	  text:'Will automatically close after 3 seconds',
	  duration:3000
});

iKnowBase.PageEngine

This object contains functions and properties relating to the page engine.

reloadComponent

The reloadComponent method on the PageEngine-object will reload the specified page component from the server, using a number of different settings. The basic syntax is “iKnowBase.PageEngine.reloadComponent (settings)”, where settings is a javascript hash containing the required settings and parameters, but there are also two old-style supported syntaxes:

It is possible to pass a set of URL-parameters for use during the reload. Whether URL-parameters are required or not, and what various parameters mean, will depend entirely on the (user defined) configuration of the specified page component.

Syntax and parameters

The basic syntax is “iKnowBase.PageEngine.reloadComponent (settings)”, where settings is a javascript hash containing the required settings and parameters. The settings object supports the following properties:

The return value from the reloadComponent is a jQuery promise object (actually a jqXHR object) making it possible to attach callbacks using methods such as done(), fail() and always(). See the example below for more information.

Note: In order to use updateHtml, the containing page region must be rendered with decorations, as specified by the page.regions FreeMarker model.

The ID of a page component is automatically and computed by the page engine, using an algorithm that may change between versions. You should generate the component ID during component rendering, using the ComponentModel expression ${component.id}. However, you may also specify the pageComponent ID in the page components tab in iKnowBase Development Studio.

The following example reloads the value of a single component, using the parameter p_document_id=1234:

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: '${component.id}',
    data: {
        p_document_id: 1234
    }
});

The following example adds the busy indicator during reload and ensures that the page component content is regenerated (and not loaded from cache):

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: '${component.id}',
    busyIndicator: true,
    refreshCache:  true,
    data: {
        p_document_id: 1234
    }
});

The following example turns off automatic display of errors, and uses the callbacks done and fail for visual status notifications:

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: id,
    errorPopup: false
}).done (function (data, textStatus, jqXHR) {
    jQuery("#" + id).css("background-color", "green");
}).fail (function (jqXHR, textStatus, errorThrown) {
    jQuery("#" + id).css("background-color", "red");
});

Finding the id of the page component

The ID of a page component is normally computed by the page engine, using an algorithm that may change between versions. You should generate the component ID during component rendering, using the FreeMarker expression ${component.id}. You may also specify a stable pageComponent ID in the page components tab in iKnowBase Development Studio, but you are then responsible for ensuring that there are no conflicts.

Use the following template in a ContentViewer to create a function that will reload the viewer with new data:

<script type="text/javascript">
    function showDocument (docid) {
        iKnowBase.PageEngine.reloadComponent ({
            pageComponent: '${component.id}',
            data: {
                p_document_id: docid
            }
        });
    }
</script>
<h2> ${viewer.data.title}</h2>

Deprecated syntax and parameters

reloadComponent still supports a less versatile syntax “iKnowBase.PageEngine.reloadComponent (pageComponent [, url] [, urlParameters]”. The traditional syntax has both url and urlParameters as optional function parameters, and it will automatically detect if they are present.

Note that reloadComponent requires that the containing component has been rendered with decorations, as specified by the page.regions FreeMarker model.

iKnowBase.PageEngine.InstantContentCache

This object contains functions and properties relating to the InstantContentCache, i.e. the mechanism that enables clients to receive notification when content caches have been updated. (Note that for this to work, the content cache key must have “publish updates to instant” enabled).

start

The reloadComponent method on the PageEngine.InstantContentCache-object will start listening for cache notifications. Before starting, it will check whether it has any page components with known cache keys; if there are none, the listening process witll not start. Whenever a notification is received, it will check whether a component with that particular cache key is known on the page; if it is, it will use PageEngine.reloadComponent to update the data.

Syntax and parameters

The basic syntax is “iKnowBase.PageEngine.InstantContentCache.start (settings)”, where settings is a javascript hash containing the required settings and parameters. The settings object is currently undocumented:

The following example will start listening to cache update notifications, using a default reloadComponent:

iKnowBase.PageEngine.InstantContentCache.start();

The following example will start listening to cache update notifications, telling the user that the page might need to be refreshed:

iKnowBase.PageEngine.InstantContentCache.start({
    reloadComponent: function (settings) {
        iKnowBase.notify ({ text:'Content has been updated. Please refresh the page.' });
    }
});

iKnowBase.Instant

The iKnowBase.Instant object contains functions related to the use of iKnowBase Instant, the component providing real time asynchronous messaging to iKnowBase. Some of the available options are in a sub-object named Atmosphere, so named to indicate that these rely on implementation details of the underlying Atmosphere framework.

For simple usage scenarios, the examples below and in the Development Guide may be sufficient; for more advanced usages you may want to consult and understand the underlying Atmosphere APIs.

Atmosphere.subscribe

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

Syntax

iKnowBase.Instant.Atmosphere.subscribe (options)

Options

The options are as follows:

The subscriptionOptions are as follows:

The atmoshpereOptions are better described in the Atmosphere documentation, but below are the most important.

Topic name and topic options

The topicName option consists of a topic base name and a set of optional topic options. The combination will uniquely identify a specific topic.

The topic base name is required to start with a “/” (forward slash) and can otherwise only contain alphanumeric characters [a-z|A-Z|0-9] and additional forward slashes. The name is case sensitive.

The topic options are added to the topic base name as URL parameters:

While the TEXT message format can be used to send any text information, the IKB message format has additional application support:

Publishers should send messages using a IKBRequestMessage:

Note: Publishers can also choose to send a simple text message to a topic with messageFormat=IKB. This message will be set as data and all optional fields will be empty.

Consumers will always receive messages as a IKBResponseMessage:

Examples

This example establishes a connection to an instant topic, with a single onMessage-callback.

var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries",
    atmosphereOptions: {
        onMessage: function (data) { /* Do something with message */ }
    }
});

This example establishes a connection to an instant topic with specified options, including:

[#ftl]
[#if context.user.isLoggedOn]
	[#assign secureTokenAuth =  "'_ikbUserToken':" + "'" + context.user.token.value + "'"]
[#else]
	[#assign secureTokenAuth = '']
[/#if]
var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries?messageFormat=IKB&userList=true",
    subscriptionOptions: {
        requestUserList: true,
        subscribeUserListChanges: true,
        ${secureTokenAuth} // Authentication header from ikbViewer
    },
    atmosphereOptions: {
        transport: "websocket",
        onMessage: function (data) { /* Do something with message */ },
        onError: function (atmosphereResponse) { /* Do something with message */ }
    }
});

Atmosphere.publish

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

Syntax

iKnowBase.Instant.Atmosphere.publish (channel, data)

Example

To send a text message on a channel with messageFormat=TEXT

iKnowBase.Instant.Atmosphere.publish (channel, "Everybody, there is cake in the reception!");

To send a direct message on a channel with messageFormat=IKB

iKnowBase.Instant.Atmosphere.publish (channel, {
    toUserName: "NARMSTRONG",
    messageType: "WALK_ON_MOON",
    data: "One giant leap, indeed!"
});

Atmosphere.unsubscribe

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

Syntax

When called without parameters, the unsubscribe-function closes all open connections

iKnowBase.Instant.Atmosphere.unsubscribe ()

When called with a single channel parameters, the unsubscribe-function closes the connection to that channel.

iKnowBase.Instant.Atmosphere.unsubscribe (channel)

Atmosphere.requestUserListUpdate

Request a userList response from the server. Same as subscription option subscribeUserListChanges, but used on demand.

Syntax

iKnowBase.Instant.Atmosphere.requestUserListUpdate (channel, correlationId)

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List.

Requirements

Active connection on a userList topic.

Example

To request a userList update:

iKnowBase.Instant.Atmosphere.requestUserListUpdate (channel, "MY_CORRELATION_ID");

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.USERS",
   "correlationId":"MY_CORRELATION_ID",
   "data":[
      {
         "guid":"BBEA12EB56126795E040000A180038B7",
         "id":58466,
         "username":"KERMIT",
         "dn":null,
         "label":"kermit frog"
      },
      {
         "guid":"8582B1E8B4AA4BDA9B7E0B6422A1D1F7",
         "id":125,
         "username":"ORCLADMIN",
         "dn":"orcladmin",
         "label":"Administrator orcladmin"
      }
   ]
}

Atmosphere.requestUserList

Request a filtered userList response from the server. Typically used to check a subset of the result from subscribeUserListChanges.

Syntax

iKnowBase.Instant.Atmosphere.requestUserList (channel, correlationId, userNames)

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List.

Requirements

Active connection on a userList topic.

Example

To request a filtered userList:

// Example where a full userList would result in ORCLADMIN and KERMIT. Apply KERMIT as filter.
iKnowBase.Instant.Atmosphere.requestUserList (channel, "MY_CORRELATION_ID", "KERMIT");

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":[
      {
         "guid":"BBEA12EB56126795E040000A180038B7",
         "id":58466,
         "username":"KERMIT",
         "dn":null,
         "label":"kermit frog"
      }
   ]
}

Atmosphere.requestSubscribeUserListChanges

Enable or disable join/leave updates for the active connection. Same as subscription option subscribeUserListChanges, but used on demand.

Syntax

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, correlationId, newSubscribeUserListChangesState)

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List.

Requirements

Active connection on a userList topic.

Example

To enable subscribeUserListChanges:

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, "MY_CORRELATION_ID", true);

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.SUBSCRIBE.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":"Change request for SubscribeUserListChanges: old=false; new=true"
}

To disable subscribeUserListChanges:

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, "MY_CORRELATION_ID", false);

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.SUBSCRIBE.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":"Change request for SubscribeUserListChanges: old=true; new=false"
}

setDefaultOptions

This method sets default options to be used for all future subscribe-calls

Syntax

iKnowBase.Instant.setDefaultOptions (options)

When called with a single channel parameters, the unsubscribe-function closes the connection to that channel

iKnowBase.Instant.Atmosphere.unsubscribe (channel)

Complete example

functon displayMessageNotification (data) {
    iKnowBase.notify({
        title: "New message received",
        text: data
    });
}

var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries",
    atmosphereOptions: {
        transport: "websocket",
        onMessage: displayMessageNotification
    }
});