| Properties Summary | |
var |
alerting
Specifies whether the Klip will alert the user, based on their settings in the 'Alert' tab of the Klip's Customize Klip window when the Klip updates. |
text |
progressmessage
Displays a progress message to the user when your Klip is doing a lengthy operation. |
String |
searchtext
The text in the search field currently being displayed. |
boolean |
searchvisible
Adds a search field to a Klip when set to true. |
String |
searchwatermark
Adds the "watermark" text to the search field. |
boolean |
usedefaultprogressmessages
Tells Klipfolio Dashboard to use its built-in progress messages (default true). |
| Function Summary | |
function
|
alert( <String> text )
Displays a message to the user in a modal dialog box. |
String
|
base64decode( <String> source )
Reverses a base64 encoding applied to a string (see RFC 1421). |
String
|
base64encode( <String> source )
Generates a base64 encoding from a text string (see RFC 1421). |
String
|
collapseWhitespace( <String> text, [<boolean> omit_newlines] )
Collapses all whitespace (\r \n \t or space characters) to a single space character. |
String
|
convertToText( <String> text, [<boolean> keep_newlines] )
Processes entities, removes XML tags, and removes whitespace for the given text. |
Timer
|
createTimer( [<integer> interval] )
Creates a Timer object that will call a JavaScript function every interval. |
function
|
delay( <integer> milliseconds )
Pauses the current JavaScript thread of execution for a number of milliseconds. |
function
|
destroyTimer( <Timer> timerObject )
Destroys a Timer object. |
String
|
garble( <String> text )
Generates an obfuscated version of a text string suitable for storage in preferences. |
function
|
getDataPool( pool_name)
Deprecated. As of Klipfolio Dashboard 5.0, replaced by Engines.DataPool.getPool(). |
String
|
md5digest( <String> text )
Generates a md5digest from a text string (see RFC 1321). |
function
|
onDrop( <String> url )
Specifies a Handler Function to call in your JavaScript when an object is dragged and dropped into Klipfolio Dashboard. |
function
|
onLoad()
Specifies a Handler Function to call in your JavaScript when Klipfolio Dashboard first loads the Klip into memory. |
function
|
onRefresh( <boolean> user_requested )
Specifies a Handler Function to call in your JavaScript when Klipfolio Dashboard sends the Klip a refresh event. |
function
|
onSearch()
Specifies a Handler Function to call in your JavaScript when user presses Enter in the search field. |
function
|
onUpgrade( [<String> version] )
Specifies a Handler Function to call in your JavaScript when Klipfolio Dashboard is upgrading the Klip. |
String
|
processEntities( <String> text )
Converts XML entities into literal characters. |
function
|
requestRefresh()
Requests Klipfolio Dashboard to enqueue your Klip for a refresh event after it exits the current event handler. |
function
|
setDataPool( pool_name, value )
Deprecated. As of Klipfolio Dashboard 5.0, replaced by Engines.DataPool.setPool(). |
String
|
stripTags( <String> text )
Strips all XML tags from a string. |
function
|
trace( <String> text )
Displays a message to the developer in the Debug Window. |
function
|
traceln( <String> text )
Displays a message followed by a carriage return and a newline (\r\n) in the Debug Window. |
String
|
ungarble( <String> garbledtext )
Ungarbles an a garbled string. |
| Properties Detail |
alerting
var alerting
-
Specifies whether the Klip will alert the user, based on their settings in the 'Alert' tab of the Klip's Customize Klip window
when the Klip updates.
The default value is true.
progressmessage
text progressmessage
-
Displays a progress message to the user when your Klip is doing a lengthy operation.
When you assign text to progressmessage, the Klip will display the message near the top of its window for 1.25 seconds.
It is helpful to let the user know the Klip is working through a lengthy operation in JavaScript, such as when logging into a remote server and making multiple requests to retrieve content.
Example:
The following Klip displays a progress message as it simulates logging into a remote system.
<klip>
<identity>
<title>
API: Klip.progressmessage
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<style>
alert {
type: item;
}
sender {
itemcol: 2;
noterow: 1;
label: 'Sender';
emphasis: strong;
}
summary {
itemcol: 3;
noterow: 4;
wrap: false;
notelabel: false;
}
date {
itemcol: 4;
noterow: 2;
label: 'Date';
}
category {
noterow: 3;
label: 'Category';
}
level {
itemcol: 1;
noterow: 5;
notelabel: false;
type: image;
}
url {
type: link;
}
id {
key: override;
}
</style>
<klipscript>
<![CDATA[
function onRefresh()
{
Klip.progressmessage = "Logging into system";
Klip.delay( 1000 );
Klip.progressmessage = "Logging into system.";
Klip.delay( 1000 );
Klip.progressmessage = "Logging into system..";
Klip.delay( 1000 );
Klip.progressmessage = "Finished";
return Engines.Data.process ( Prefs.contentsource );
}
]]>
</klipscript>
</klip>
searchtext
String searchtext
-
The text in the search field currently being displayed.
searchvisible
boolean searchvisible
-
Adds a search field to a Klip when set to true.
Klip.searchvisible = true;
searchwatermark
String searchwatermark
-
Adds the "watermark" text to the search field. Only displayed when the search field is empty.
Klip.searchwatermark = "Enter a search term";
usedefaultprogressmessages
boolean usedefaultprogressmessages
-
Tells Klipfolio Dashboard to use its built-in progress messages (default true).
When set to true, Klipfolio Dashboard will display the built-in progress messages taken from the Klip's parameters <loading> and <nodata>. If these parameters do not exist, the Klip will use the following values:
<messages> <loading>Getting items...</loading> <nodata>No items to display.</nodata> </messages>
| Function Detail |
alert
function alert( <String> text )
- Displays a message to the user in a modal dialog box.
Note: Klipfolio Dashboard will not display the modal dialog box unless alert is called from within an event handler, such as onLoad(), onRefresh(), and onUpgrade() and Klipfolio Dashboard has 'developer mode' enabled. To enable developer mode, see Enabling Developer Mode.
Example:
The following Klip displays an alert dialog each time the Klip receives an onLoad() and onRefresh() event.
<klip>
<identity>
<title>
API: Klip.alert()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<style>
alert {
type: item;
}
sender {
itemcol: 2;
noterow: 1;
label: 'Sender';
emphasis: strong;
}
summary {
itemcol: 3;
noterow: 4;
wrap: false;
notelabel: false;
}
date {
itemcol: 4;
noterow: 2;
label: 'Date';
}
category {
noterow: 3;
label: 'Category';
}
level {
itemcol: 1;
noterow: 5;
notelabel: false;
type: image;
}
url {
type: link;
}
id {
key: override;
}
</style>
<klipscript>
<![CDATA[
function onLoad()
{
alert( "onLoad()" );
}
function onRefresh()
{
alert( "onRefresh()" );
return Engines.Data.process( Prefs.contentsource );
}
]]>
</klipscript>
</klip>
-
Parameters:
text - the text to display in modal dialog box
base64decode
String base64decode( <String> source )
- Reverses a base64 encoding applied to a string (see RFC 1421).
-
Parameters:
source - text to decode
-
Returns:
-
the decoded version of a base64 encoded block of source text
base64encode
String base64encode( <String> source )
- Generates a base64 encoding from a text string (see RFC 1421).
-
Parameters:
source - text to encode
-
Returns:
-
the base64 encoding of the source text
collapseWhitespace
String collapseWhitespace( <String> text, [<boolean> omit_newlines] )
- Collapses all whitespace (\r \n \t or space characters) to a single space character.
Example:
The following Klip uses collapseWhitespace function to remove whitespace from a string.
The first call collapseWhitespace(text, false) does not collapse newlines, the second
collapseWhitespace(text, true) includes collapsing of newlines.
<klip>
<identity>
<title>
API: Klip.collapseWhitespace()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<klipscript>
<![CDATA[
function onLoad()
{
var text =
"<x>\r\n" +
"<y>B&B Breakfast</y>\r\n\r\n\r\n" +
"<x>text with ", <, >, and ' characters</x>\r\n" +
"</x>\r\n";
trace( "# text\r\n" );
trace( text + "\r\n\r\n" );
trace( "# collapseWhitespace (text, false)\r\n" );
trace( Klip.collapseWhitespace( text, false ) + "\r\n\r\n" );
trace( "# collapseWhitespace (text, true)\r\n" );
trace( Klip.collapseWhitespace( text, true ) + "\r\n\r\n" );
}
function onRefresh()
{
var xml = "<xml><item><link></link><description>" +
"(See Debug Window for output)" +
"</description></item></xml>";
return Engines.Data.process( xml );
}
]]>
</klipscript>
</klip>
# text # collapseWhitespace (text, false) <x> <y>B&B Breakfast</y> <x>text with ", <, >, and ' characters</x> </x> # collapseWhitespace (text, true) <x> <y>B&B Breakfast</y> <x>text with ", <, >, and ' characters</x> </x>
-
Parameters:
text - text to collapse
omit_newlines - true to leave newlines unchanged (default false)
-
Returns:
-
updated string with all whitespace collapsed to a single space character
convertToText
String convertToText( <String> text, [<boolean> keep_newlines] )
- Processes entities, removes XML tags, and removes whitespace for the given text.
Example:
The following Klip uses convertToText.
<klip>
<identity>
<title>
API: Klip.convertToText()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<klipscript>
<![CDATA[
function onLoad()
{
var text =
"<x>\r\n" +
"<y>B&B Breakfast</y>\r\n\r\n\r\n" +
"<x>text with ", <, >, and ' characters</x>\r\n" +
"</x>\r\n";
trace( "# text\r\n" );
trace( text + "\r\n\r\n" );
trace( "# convertToText ( text, false )\r\n" );
trace( Klip.convertToText( text, false ) + "\r\n\r\n" );
trace( "# convertToText ( text, true )\r\n" );
trace( Klip.convertToText( text, true ) + "\r\n\r\n" );
}
function onRefresh()
{
var xml = "<xml><item><link></link><description>" +
"(See Debug Window for output)" +
"</description></item></xml>";
return Engines.Data.process( xml );
}
]]>
</klipscript>
</klip>
# text <x> <y>B&B Breakfast</y> <x>text with ", <, >, and ' characters</x> </x> # convertToText ( text, false ) B&B Breakfast text with ", <, >, and ' characters # convertToText ( text, true ) B&B Breakfast text with ", <, >, and ' characters
-
Parameters:
text - text to collapse
keep_newlines - true to leave newlines unchanged (default false)
-
Returns:
-
updates string with all whitespace collapsed to a single space character
createTimer
Timer createTimer( [<integer> interval] )
- Creates a Timer object that will call a JavaScript function every interval.
-
Parameters:
interval - time (milliseconds) to wait before calling timer [optional]
-
Returns:
-
a new Timer object configured to use the specified url
delay
function delay( <integer> milliseconds )
- Pauses the current JavaScript thread of execution for a number of milliseconds.
This is useful for pausing between TCPConnection.receive() when reading from a TCP/IP socket. There is no need to use delay when reading from a HTTP connection using Engines.HTTP.
-
Parameters:
milliseconds - number of milliseconds to delay (max 1000)
destroyTimer
function destroyTimer( <Timer> timerObject )
- Destroys a Timer object.
-
Parameters:
timerObject - Timer object to destroy
garble
String garble( <String> text )
- Generates an obfuscated version of a text string suitable for storage in preferences.
Use ungarble() to ungarble the string.
Example:
The following Klip garbles and ungarbles a message.
<klip>
<identity>
<title>
API: Klip.garble()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<klipscript>
<![CDATA[
function onLoad() {
text = "This is some text to garble.";
trace( "Original: " + text + "\r\n" );
trace( "Garbled: "
+ Klip.garble( text )
+ "\r\n" );
trace( "UnGarbled: "
+ Klip.ungarble( Klip.garble( text ) )
+ "\r\n" );
}
function onRefresh()
{
var xml = "<xml><item><link></link><description>" +
"(See Debug Window for output)" +
"</description></item></xml>";
return Engines.Data.process( xml );
}
]]>
</klipscript>
</klip>
Original: This is some text to garble. Garbled: VGhpcyBpcyBzb21lIHRleHQgdG8gZ2FyYmxlLg== UnGarbled: This is some text to garble.
-
Parameters:
text - plain text string to obfuscate
-
Returns:
-
the obfuscated version of text
getDataPool
function getDataPool( pool_name)
- Deprecated. As of Klipfolio Dashboard 5.0, replaced by Engines.DataPool.getPool().
md5digest
String md5digest( <String> text )
- Generates a md5digest from a text string (see RFC 1321).
-
Parameters:
text - source text to generate MD5 digest
-
Returns:
-
A 32 character long hexadecimal MD5 digest based on the source text
onDrop
function onDrop( <String> url )
- Specifies a Handler Function to call
in your JavaScript when an object is dragged and dropped into Klipfolio Dashboard.
Example:
The following function will do something you specify when user drops a URL object into Klipfolio Dashboard.
Klip.onDrop = dropURL;
// ...
function dropURL (url)
{
if (typeof (url) == "string")
{
// Do something with url...
}
}
-
Parameters:
url - URL of the dropped object
onLoad
function onLoad()
- Specifies a Handler Function to call
in your JavaScript when Klipfolio Dashboard first loads the Klip into memory.
Example:
The following function outputs a message on loading.
function onLoad() {
trace( "Loading the Klip ...\r\n" );
// An onLoad() function typically
// - reads preferences
// - creates UI in Klip setup window
// - update/add/delete items in the Klip's window
trace( "... loading complete.\r\n" );
}
onRefresh
function onRefresh( <boolean> user_requested )
- Specifies a Handler Function to call
in your JavaScript when Klipfolio Dashboard sends the Klip a refresh event.
Example:
The following function outputs a message when the Klip refreshes.
function onRefresh() {
trace( "Refreshing the Klip ...\r\n" );
// An onRefresh() function typically
// - downloads new items from remote sources
// - updates/adds/deletes items in the Klip's window
// - updates the icon (upper-left) and status (lower-left)
trace( "... refresh complete.\r\n" );
return true;
}
You can call your refresh function whatever you like, just assign it to
Klip.onRefresh. For Example,
Klip.onRefresh = myOnRefresh;
function myOnRefresh() {
trace( "Inside myOnRefresh ...\r\n" );
return true;
}
Return value from onRefreshKlipfolio Dashboard checks the boolean return value from your OnRefresh handler.
When the return value is true, Klipfolio Dashboard sets your Klip to the normal 'fresh' state:
When the return value is false, Klipfolio Dashboard sets your Klip to a 'stale' state, which indicates to users the Klip's information might be out of date.
Finally, not specifying a return value for your OnRefresh handler is the same as returning false.
-
Parameters:
user_requested - is true when the onRefresh handler was triggered by a user's action, such as when the user clicks the 'Refresh Klip' button in the Customize Klip window or right-clicks on the Klip's title bar and selects 'Refresh'. Klipfolio Dashboard also passes true to the first call to onRefresh on startup as starting Klipfolio Dashboard is considered a user action. Checking this parameter is useful when you want to bypass logic that may be causing Klipfolio Dashboard to ignore periodic refresh events, when a Klip is running late at night, for example.
onSearch
function onSearch()
- Specifies a Handler Function to call in your JavaScript when user presses
Enter in the search field.
onUpgrade
function onUpgrade( [<String> version] )
- Specifies a Handler Function to call
in your JavaScript when Klipfolio Dashboard is upgrading the Klip.
Example:
The following function outputs a message on upgrade.
function onUpgrade() {
trace( "Upgrading the Klip ...\r\n" );
// An onUpgrade() function typically
// - refreshes all the items in the Klip's window
// - migrates the user's preferences (if necessary)
trace( "... upgrade complete.\r\n" );
}
-
Parameters:
version - the previous version of the Klip
processEntities
String processEntities( <String> text )
- Converts XML entities into literal characters.
- & - to produce the & character
- < - to produce the < character
- > - to produce the > character
- " - to produce the " character
- ' - to produce the ' character
- ä - to produce the ä character
Processes:
and all other XML and SGML defined entities.
Example:
The following Klip uses processEntities to convert XML entities.
<klip>
<identity>
<title>
API: Klip.processEntities()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<klipscript>
<![CDATA[
function onLoad() {
var text =
"<x>\r\n" +
"<y>B&B Breakfast</y>\r\n\r\n" +
"<z>text with ", <, >, and ' characters</z>\r\n" +
"</x>\r\n";
trace( "# text\r\n" );
trace( text + "\r\n\r\n" );
trace( "# Klip.processEntities( text ) \r\n" );
trace( Klip.processEntities( text ) );
}
function onRefresh()
{
var xml = "<xml><item><link></link><description>" +
"(See Debug Window for output)" +
"</description></item></xml>";
return Engines.Data.process( xml );
}
]]>
</klipscript>
</klip>
# text <x> <y>B&B Breakfast</y> <z>text with ", <, >, and ' characters</z> </x> # Klip.processEntities( text ) <x> <y>B&B Breakfast</y> <z>text with ", <, >, and ' characters</z> </x>
-
Parameters:
text - string containing XML entities
-
Returns:
-
A copy of text where all substrings identifiable as XML entities have been translated to their literal characters
requestRefresh
function requestRefresh()
- Requests Klipfolio Dashboard to enqueue your Klip for a refresh event after it exits the current event handler.
setDataPool
function setDataPool( pool_name, value )
- Deprecated. As of Klipfolio Dashboard 5.0, replaced by Engines.DataPool.setPool().
stripTags
String stripTags( <String> text )
- Strips all XML tags from a string.
Example:
The following Klip uses StripTags strip all XML tags from a string.
# text <x> <y>B&B Breakfast</y> <x>text with ", <, >, and ' characters</x> </x> # stripTags (text) B&B Breakfast text with ", <, >, and ' characters
-
Parameters:
text - string containing XML tags
-
Returns:
-
Text string stripped of XML tags
trace
function trace( <String> text )
- Displays a message to the developer in the Debug Window.
Note: To see the Debug Window, you must enable 'developer mode' in Klipfolio Dashboard. To enable developer mode, see Enabling Development Tools.
Example:
The following Klip displays 'Hello, World!' and the current version of Klipfolio Dashboard in the Debug Window:
<klip>
<identity>
<title>
API: Klip.trace()
</title>
</identity>
<locations>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
<icon>
http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
</icon>
<banner>
http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png
</banner>
</locations>
<style>
alert {
type: item;
}
sender {
itemcol: 2;
noterow: 1;
label: 'Sender';
emphasis: strong;
}
summary {
itemcol: 3;
noterow: 4;
wrap: false;
notelabel: false;
}
date {
itemcol: 4;
noterow: 2;
label: 'Date';
}
category {
noterow: 3;
label: 'Category';
}
level {
itemcol: 1;
noterow: 5;
notelabel: false;
type: image;
}
url {
type: link;
}
id {
key: override;
}
</style>
<klipscript>
<![CDATA[
function onLoad() {
trace( "Hello, World!\r\n" );
trace( "You are running " + KlipFolio.version + "\r\n");
}
function onRefresh() {
return Engines.Data.process( Prefs.contentsource );
}
]]>
</klipscript>
</klip>
-
Parameters:
text - the text to display in the Debug Window
traceln
function traceln( <String> text )
- Displays a message followed by a carriage return and a newline (\r\n) in the Debug Window.
Note: To see the Debug Window, you must enable 'developer mode' in Klipfolio Dashboard. To enable developer mode, see Enabling Development Tools.
-
Parameters:
text - the text to display in the Debug Window
ungarble
String ungarble( <String> garbledtext )
- Ungarbles an a garbled string.
See garble() for an example.
-
Parameters:
garbledtext - text to ungarble
-
Returns:
-
the original string previously obfuscated with the garble() function
|
Klipfolio Dashboard 5 API | ||||||||
| PREV OBJECT NEXT OBJECT | FRAMES NO FRAMES | ||||||||
| SUMMARY: PROPERTY | FUNCTION | DETAIL: PROPERTY | FUNCTION | ||||||||
© 2009 Klipfolio Inc. All Rights Reserved.



