To write your own logic in a Klip, you need to know two things: the events and the Klipfolio Dashboard API.
Like any full-featured API, the Klipfolio Dashboard API has numerous objects, functions, and properties that can help you build custom Klips. Of those, you will want to familiarize yourself the most with the following:
the Engines.Data object
the Items object
event callbacks from Klipfolio Dashboard's XML parser
The Engines.Data object lets you call Klipfolio Dashboard's XML parser. The most common use of this object is to call Engines.Data.process() with a URL, usually the one in <contentsource> though you can use any URL you want.
Your JavaScript can then access the parameters passed in the Klip. For example,
var cs = Prefs.contentsource;
uses the Prefs object to read the contents of <contentsource> into the variable cs. And here's a working onRefresh() that processes the remote data pointed to by <contentsource>:
function onRefresh ()
{
var cs = Prefs.contentsource;
if (cs != undefined)
{
return Engines.Data.process (cs);
}
return false;
}
If the Klip does not have JavaScript in its source, Klipfolio Dashboard will provide the above code as the Klip's JavaScript internally.
For example, in the previous chapter, the following URL was used as an example:
<contentsource> http://support.klipfolio.com/files/demo/demo.xml </contentsource>
When you loaded the basic Klip, the application was actually running the following code (the portions that are not relevant to the current discussion are omitted):
<?xml version='1.0' ?>
<klip>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
</locations>
<klipscript>
<![CDATA[
function onRefresh ()
{
var cs = Prefs.contentsource;
if (cs != undefined)
{
return Engines.Data.process (cs);
}
return false;
}
]]>
</klipscript>
</klip>Each visible item in a Klip has a corresponding entry in the Items object. When an item is deleted from a Klip, Klipfolio Dashboard moves the item from Items to Items.Deleted. These objects are also accessible as arrays, so they are also referred to as Items[] and Items.Deleted[] arrays.
In the previous chapter under the section, Displaying the items you intend to display, the comparison between the incoming items and existing items was mentioned. Here is a more detailed view of that process:
Make an HTTP (GET) request to the <contentsource> URL, which is now in the variable cs.
Check for a valid response from the server and confirm that the request returned data.
Parse the data by first looking for the repeating block of XML, as defined in the <style> block.
For each repeating block of XML, create a new item by mapping the XML to columns in the item and rows in the item's tooltip, as defined in the <style> block.
If the item exists in Items.Deleted[], discard it. If the item already exists in Items[], overwrite it; otherwise, insert it at Items[0].
