What's New in Klipfolio Dashboard 5 API

New objects and methods are introduced in addition to new properties and methods for existing objects.

Some of the objects are special features not available in Klipfolio Personal Dashboard. They are indicated with this icon: . In order to use these features in Klipfolio Personal Dashboard, be sure to include <enterprise>true</enterprise> in your <setup> block.

Actions.Button

This new object allows you to display a button in an empty Klip.

Actions.Window

You can create pop-up windows that prompt users for their input with Action Windows.

Actions.Window.Back, Actions.Window.Next, Actions.Window.Done

With these new objects, you can globally control the properties of your Actions.Window's Back, Next, and Done buttons, respectively.

Stack

Your Actions.Window object will contain one or more Stacks.

Page

Each of your Stack objects can contain one or more Pages to which you can add various elements in order to ask for and get user input.

Engines.ReportingServices

This object provides access Microsoft SQL Server Reporting Services APIs.

Engines.ODBC, Engines.ODBC.ODBCResponse

These new objects enable you to access a built-in SOAP API.

Engines.SOAP, Engines.SOAP.SOAPClient, Engines.SOAP.SOAPResponse

These objects provide you with access to the ODBC APIs.

Item

Custom menu items for specific items in your Klip can be added with Item.actions.

Items

For custom menu options you want to apply to all items in your Klip, use Items.actions. You can also add custom options to the Klip's menu using Items.globalactions.

Engines.KlipFood

Support for parsing CSV has been added. See format for details.

Klip

Support to handle drag-and-drop events has been added. See onDrop for details.
Klips can now share data with each other. See Klip.setDataPool() and Klip.getDataPool().
Search fields can now be added using Klip.searchvisible. Use Klip.searchwatermark and Klip.searchtext properties to customize the search field.
You can specify a search handler using Klip.onSearch().

Handler Functions

The concept of a handler function is important to understand as it is how your JavaScript responds to incoming events.

A handler function is a function you define in JavaScript that Klipfolio Dashboard calls when a Klip lifecycle event occurs (such as when Klipfolio Dashboard requests your Klip to refresh) or a user event occurs (such as when the user clicks on the first item in your Klip).

Lifecycle Events

For lifecycle events, which are Klip.onDrop, Klip.onLoad, Klip.onRefresh, Klip.onSearch and Klip.onUpgrade, Klipfolio Dashboard will call a function in your JavaScript if you have created a function of the same name, such as

function onRefresh() {
   trace( "Inside myOnRefresh ...\r\n" );

   // your code here
}

or you can explicitly assign an onRefresh() handler

Klip.onRefresh = myOnRefresh; 

function myOnRefresh() { 
  trace( "Inside myOnRefresh ...\r\n" );

   // your code here
}

The first example works because your JavaScript (where you define all your functions) is running in the global scope with the Klip object as its root. Technically speaking, when you say function myfunction {...} you're actually saying (as far as Klipfolio Dashboard is concerned) Klip.myfunction = function {...}

User Events

For user events, you need to assign the handler function explicitly to a property of whichever Klipfolio Dashboard API object can receive an event.

For example, if you want to have Klipfolio Dashboard call your function for every item a user clicks on in your Klip, you will have to assign your handler function to the Items.onClick property of the Items object itself:

Items.onClick = myItemsOnClick;
function myItemsOnClick() { ... }
       // your code here
}

Updating a UI Component in Klip's Customize Window

If you define a handler function for a UI component, such as Button.onClick for a Button object, Klipfolio Dashboard does not complete a UI component's behaviour until its handler function returns. This means a button, for example, will stay depressed until its associated Button.onClick function returns.

Therefore, to avoid slowing down the user interface and causing problems for your users, you should avoid performing complex calculations and making network connections during your user interface event handler functions.

For example, if your Klip requires a complex or lengthy operation, it is best to set a global state flag, make a request Klip.requestRefresh(), which causes Klipfolio Dashboard to send an onRefresh() event as soon as the current event handler exits. Before calling onRefresh, Klipfolio Dashboard will update the state of all UI components. In the onRefresh() handler, the function can test the state flag to do the lengthy operation..

Klipfolio Dashboard Threading Model

Each Klip has a single-thread execution model. This makes it easy to program in JavaScript, but it means that incoming events may queue up. (Klipfolio Dashboard itself is multi-threaded and can update a number of Klips simultaneously.)

For example, if Klipfolio Dashboard is in the process of executing a user handler function and it's time to send the Klip refresh event, Klipfolio Dashboard will wait until your user event handler is finished before calling your Klip.onRefresh handler function.

Specifically, when the thread of execution leaves your handler function, say a Button.onClick handler function, your Klip.onRefresh handler will be called.

To ensure the user cannot inadvertently queue up multiple events -- and put your Klip into an unknown state -- Klipfolio Dashboard temporarily disables user input to your Klip's setup components when executing a handler function. To the user, the components don't appear disabled; rather, the user's mouse changes to an hour glass. For example, imagine a Klip has two checkboxes, where checking the first disables the second. If the event handler for the first checkbox was supposed to cause a second checkbox to be removed, and the onClick handler function could not be called because your onRefresh handler function was still busy downloading a file, the second checkbox would not be removed and the user would be able to click on it.

If these events piled up, waiting for the onRefresh handler function to return, you would need a lot of code to handle unexpected cases. Klipfolio Dashboard keeps the event model simple so you can keep your code simple.

Klip Root Object is Optional

The root Klip object is implied when making KlipScript API. This means you can write

   		Klip.Items.icon = "http://www.mysite.com/images/myKlipIcon.gif";
   		Klip.Setup.AddTab( "New Tab" );
	

or simply write the following:

   		Items.icon = "http://www.mysite.com/images/myKlipIcon.gif";
   		Setup.AddTab( "New Tab" );