What's New in Klipfolio Dashboard API

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

Note:
Objects and functions marked with this icon are only available in the licensed, commercial version of Klipfolio Dashboard. Contact Klipfolio for further details.

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.

• In version 5.2.1, a new property, Actions.Window.defaultbutton, was added.

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.

Engines.Data

• Support for parsing CSV has been added. See format for details.
• In version 5.0.1, a new function, applyStyle(), was added.
• In version 5.4, a new function, processTile(), was added.

Engines.DataPool

Since version 5.0.1. This new object has 3 functions that can be used to store and retrieve values that are shared by multiple Klips. Functions getPool() and setPool() replaced Klip.getDataPool() and Klip.setDataPool(), respectively.

Engines.Excel

• Since version 5.2. This new object adds support for parsing Excel worksheets.
• Since version 5.3. Excel workbooks with the XLSX file extension are supported in addition to XLS.

Engines.HTTP.HTTPRequest

Since version 5.3. The following new property and functions have been added for making and handling an asynchronous HTTP request:

• Engines.HTTP.HTTPRequest.state
• Engines.HTTP.HTTPRequest.onData
• Engines.HTTP.HTTPRequest.onStateChange
• Engines.HTTP.HTTPRequest.sendAsync

Engines.JSON

Since version 5.3. This new object provides you with methods to convert a JavaScript object to a string in JSON syntax and vice versa.

Engines.KlipFood

Deprecated as of version 5.0. This object has been replaced by Engines.Data.

Engines.LDAP

Since version 5.4. This new object allows you to run a query against the default Active Directory provider.

Engines.Login

Since version 5.3. This new object allows you to set up a login UI using Klipfolio Dashboard's Login extension.

Engines.ODBC Upd, Engines.ODBC.ODBCResponse

These objects provide you with access to the ODBC APIs.

• Since version 5.3. Engines.ODBC.getLastError gives you the description of the most recent error.
• Since version 5.5. Engines.ODBC.commandtimeout allows you to specify the amount of time (in seconds) before connection times out.

Engines.ReportingServices

This object provides access Microsoft SQL Server Reporting Services APIs.

Engines.Salesforce, Engines.SalesforceLogin, Engines.SalesforceReports

Since version 5.2.1. These objects offer access to the Salesforce.com data.

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

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

Item

• Custom menu items for specific items in your Klip can be added with Item.actions.
• In version 5.4, a new function, Item.showarrow, was added.

Items Upd

• 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.
• From version 5.4, the following functions that can be used with the new Tile object are available: Items.autodrilldown, Items.loadTile, Items.newTile, Items.onBack, and Items.showbackbutton.
• Since version 5.5. Items.clearStyles can be used to clear the item styles and the items permanently during Klip upgrade.

Items.Results

Since version 5.1. This object provides an API to get the result of a formula in a column of numbers (type: number).

Klip

• Support to handle drag-and-drop events has been added. See onDrop for details.
• 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().
• Since version 5.0.1, Klip.setDataPool() and Klip.getDataPool() have been replaced by getPool() and setPool(), respectively.
• Since version 5.3, a new function, Klip.sha1digest() is available.

Klipfolio New

As of version 5.5, this object replaces the KlipFolio object. Note the use of the lower-case f in the new object.

KlipFolio

Deprecated as of version 5.5 and replaced by the Klipfolio object, with a lower-case f.

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.

Stack

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

Text

Since version 5.1. A new property, Text.url, has been added to allow a displayed URL to be linkable in an Action Window.

Tile

Since version 5.4. With this new object, you can create multiple arrays of Items in a single Klip. All properties and functions that are available for the Items object are available for this object.

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() {
   traceln( "Inside myOnRefresh ..." );

   // your code here
}

or you can explicitly assign an onRefresh() handler

Klip.onRefresh = myOnRefresh; 

function myOnRefresh() { 
  traceln( "Inside myOnRefresh ..." );

   // 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" );