Object
   |
   +--Klip
         |
         +--Items

The Items object provides an interface to the Klip's icon, Klip's status area (which usually shows the number of unvisited items) and, most importantly, an array interface to items in the Klip, hereafter referred to as the Items[] array.

For example, a new Klip starts with an empty Items[] array. If after the first refresh the user sees 10 items in the Klip, then Items[] holds 10 items indexed as Items[0] to Items[9].

Each index in the Items[] array returns an Item object. The most common use of the Item object is to call Item.getData() and Item.setData().

How KlipFlio Updates Items[]

When your Klip calls Engines.Data.process() during refresh, Klipfolio Dashboard accesses the remote <contentsource>, parses the XML according to the instructions in the Klip's <style> parameter, and updates Items[].

During parsing, each item that Engines.Data.process() extracts from <contentsource> creates an Item object. Engines.Data.process() inserts this new Item at the top of the Items[] array if it does not already exist (in which case it updates the existing item) or has not been previously deleted (in which case it discards the incoming item).

Use Engines.Data.process() to add new items to the Klip. If you want to add an item without using a remote content source, simply create a string that has the XML for the new item and call Engines.Data.process().

---

Nested Object Summary
<static class>	Items.Deleted

 

Properties Summary
boolean	autoremove           Specifies whether Klipfolio Dashboard automatically removes items in a Klip according to the user's global Item Management settings (default true).
boolean	banner           Specifies a banner for the Klip's Customize window.
boolean	canalert           Specifies whether Klipfolio Dashboard should alert the user when creating a new item or updating an existing item based on the user's alerting preferences (default true).
String	icon           Specifies the icon displayed in the icon area (upper-left) of your Klip.
String	iconAlt           Specifies the text displayed in a tooltip when the user hovers their mouse over the icon area (upper-left corner of your Klip).
boolean	iconvisible           Specifies whether the icon area (upper-left corner of Klip) is visible (default true).
integer	length           Returns the number of Item objects contained in your Klip (read-only).
boolean	removeduplicates           Specifies whether Klipfolio Dashboard should check for duplicate items (default true).
boolean	savehistory           Specifies whether Klipfolio Dashboard should disable the Klip's loading and saving of history (default true).
String	status           Specifies the content displayed in the status area (top-left corner of your Klip).
String	statusAlt           Specifies the text displayed in the tooltip for the status area (top-left) of your Klip.
boolean	statusvisible           Specifies whether the status area (top-left corner of Klip) is visible (default true).

   

Function Summary
array	actions( <String> text1, <function> function1[, <String> text2, <function> function2, ...])            Adds a custom menu option(s) above "Copy" in the menu that appears when the user right-clicks on any item in a Klip.
function	clear( [<boolean> permanently] )            Clears all entries in the Items[] array (user will see an empty Klip).
integer	findItemByIID( <String> iid )            Returns the index of the item in the Items array that matches the specified iid.
array	globalactions( <String> text1, <function> function1[, <String> text2, <function> function2, ...])            Adds a custom menu option(s) above "Refresh" in the Klip Menu.
function	onClick( [<integer> index], [<String> style] )            Specifies a Handler Function for Klipfolio Dashboard to call in your JavaScript when the user clicks on any item in the Klip.
boolean	onDelete( [<integer> index] )            Specifies a Handler Function for Klipfolio Dashboard to call in your JavaScript when the user attempts to delete any item in a Klip.
function	processAutoRemove()            Requests Klipfolio Dashboard to immediately remove all items that are older than the user's Klipfolio Dashboard preferences setting.
function	purge( [<boolean> permanently] )            Removes all un-modified entries in the Items array at the end of the Klip.onRefresh() event.
boolean	remove( <Item> item | <integer> index [, <boolean> permanently] )            Removes an existing item from the Klip.
function	sort( <String> sortBy | <boolean> reversed )            Sorts items based on the specified sort option.

Properties Detail

autoremove

boolean autoremove

Specifies whether Klipfolio Dashboard automatically removes items in a Klip according to the user's global Item Management settings (default true).

The global Item Management settings refers to the setting for 'Automatically remove old items:' option in the 'Items' tab of the Klipfolio Dashboard's Options window. Klipfolio Dashboard normally applies these settings whenever Klip.onRefresh() returns a true.

Setting Items.autoremove to false disables Klipfolio Dashboard's automatic deletion of older items.

You can use autoremove to set the autoremove property on an item by item basis. Klipfolio Dashboard checks the global autoremove property before checking an individual Item.autoremove property. In other words, if you set autoremove to false, Klipfolio Dashboard will not automatically purge any items even if the individual Item.autoremove is set to true.

This property is useful when making a dashboard Klip, which is a Klip that always shows the current contents of a remote source, as in the following example.



<klip>
   <identity>
      <title>
         API: Items.autoremove
      </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()
{
    // Disable Klipfolio Dashboard's automatic item removal
    Items.autoremove = false;
   
    var req = Engines.HTTP.newRequest (Prefs.contentsource);
       
    if (!req.send())
    {
        // return false if request failed
        return false;
    }
   
    var data = req.response.data;

    if (!data.length)
    {
        // return true if web server indicates file has not changed since last request
        return (req.response.headers.indexOf( "304 Not Modified" ) != -1);
    }


    // Show only current items in source
    Items.purge ();


    return Engines.Data.process (data);
}
   ]]>
   </klipscript>
</klip>

     	

---

banner

boolean banner

Specifies a banner for the Klip's Customize window.

There are two limitations with this property: the Klip must not have a <banner> already defined in the <locations> block, and you may only set the banner once.

---

canalert

boolean canalert

Specifies whether Klipfolio Dashboard should alert the user when creating a new item or updating an existing item based on the user's alerting preferences (default true).

The preferences refers to the setting for 'Alert me when:' in the 'Alerts' Tab of the Customize Klip window. Klipfolio Dashboard sends alerts when Klip.onRefresh() returns a true.

Setting Items.canalert to false disables alerts for this Klip.

This property is useful when manipulating status-related items in your Klip and you don't want Klipfolio Dashboard to alert the user when making a change to the items.

Note: This property applies to all items in the Klip.

---

icon

String icon

Specifies the icon displayed in the icon area (upper-left) of your Klip.
• If set to a valid image URL (PNG 8-bit, PGN 24-bit, GIF, or ICO), Klipfolio Dashboard displays that image in the icon area.
• If set to an empty string, Klipfolio Dashboard displays the default icon specified in the Klip's setup file.
• If set to a string containing text other than a URL, Klipfolio Dashboard will display that text in the icon area.
To remove the icon, set iconvisible to false.

---

iconAlt

String iconAlt

Specifies the text displayed in a tooltip when the user hovers their mouse over the icon area (upper-left corner of your Klip).

Example:
The following Klip creates three new items and specifies a tooltip for the icon area.



<klip>
   <identity>
      <title>
         API: Items.iconAlt
      </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() {  

    Items.iconAlt = "This is a specific message\nAnd a second line\nAnd a third";
 }   
 

function onRefresh()
{
    var xml = "<xml><item><link></link><description>" +
          "(Move cursor over icon)" +
          "</description></item></xml>";
             
     return Engines.Data.process( xml );
}

   ]]>
   </klipscript>
</klip>

     	

If you don't specify a tooltip for iconAlt, Klipfolio Dashboard uses the value specified by the <title> element in the Klip's source.

---

iconvisible

boolean iconvisible

Specifies whether the icon area (upper-left corner of Klip) is visible (default true).

---

length

integer length

Returns the number of Item objects contained in your Klip (read-only).

---

removeduplicates

boolean removeduplicates

Specifies whether Klipfolio Dashboard should check for duplicate items (default true).

This property lets you optimize a Klip's execution by disabling the checking of incoming items against existing items. Use this if you Klip contains a large number of items (i.e. many thousands) and the data source guarantees that on each request it only returns new items.

---

savehistory

boolean savehistory

Specifies whether Klipfolio Dashboard should disable the Klip's loading and saving of history (default true).

This property lets you optimize a Klip's execution; when set to false, Klipfolio Dashboard does not store the Klip's current items to disk. This means the Klip will always be empty on startup (before its first refresh).

---

status

String status

Specifies the content displayed in the status area (top-left corner of your Klip).
• If set to a valid image URL (PNG 8-bit, PGN 24-bit, GIF, or ICO), Klipfolio Dashboard displays that image in the status area.
• If set to an empty string, Klipfolio Dashboard displays the number of un-visited visible items in the Klip.
• If set to a string containing text other than a URL, Klipfolio Dashboard will display that text in the status area.

To remove the status area, set statusvisible to false.

---

statusAlt

String statusAlt

Specifies the text displayed in the tooltip for the status area (top-left) of your Klip.

Example:
The following function creates three new items and specifies an alternate phrase for the icon area's tooltip.

 function onLoad() {
 
     Items.create( "My First Item");
     Items.create( "My Second Item" );
     Items.create( "My Third Item" );
     
     Items.statusAlt = "Alternate status text.";
 }  
 
 function onRefresh() {
     return true;
 }
 

When the user hovers their mouse over the status area, Klipfolio Dashboard will display the following tooltip:



If you don't specify a tooltip for statusAlt, Klipfolio Dashboard displays a messages that specifies how many items the user has visited (clicked on) or not, such as "15 unvisited [1 visited]".

---

statusvisible

boolean statusvisible

Specifies whether the status area (top-left corner of Klip) is visible (default true).

---

Function Detail

actions

array actions( <String> text1, <function> function1[, <String> text2, <function> function2, ...])

Adds a custom menu option(s) above "Copy" in the menu that appears when the user right-clicks on any item in a Klip. Specify an array of pairs of text to display as a new option in the menu and an associated function.

Note: The location of the custom menu option(s) is not configurable.

Custom menu options are not saved across Klipfolio Dashboard sessions; therefore, they must be set each time the Klip is loaded.

Be sure to include the item object as a parameter for the function callback.

Example:
The following example illustrates how to add custom menu options. When you right-click on any of the items in this Klip, 'Custom Menu Option 1' and 'Custom Menu Option 2' will be displayed above 'Copy' option in the menu.



<?xml version='1.0' ?>
<klip>
	<identity>
		<title>
			API - Items.action
		</title>
	</identity>

	<locations>
		<contentsource>
		<![CDATA[
			<item>
				<product>oranges</product>
			</item>
			<item>
				<product>bananas</product>
			</item>
			<item>
				<product>apples</product>
			</item>
			<item>
				<product>grapes</product>
			</item>
			<item>
				<product>peaches</product>
			</item>
		]]>
		</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>
	item {
		type: item;
		definition: all;   
	}

	product {
		itemcol: 1;
		noterow: 1;
	}
	</style>
  
	<klipscript>
	<![CDATA[

		function onRefresh() {
			// Add 2 custom menu options for all items
			Items.actions = [ "Custom Menu Option 1", firstFunction, "Custom Menu Option 2", secondFunction ];

			return Engines.Data.process(Prefs.contentsource);
		}

		function firstFunction(item) {
			trace( "1st menu option was clicked for " + item.getData( "product" ) + "\r\n" );
		}

		function secondFunction(item) {
			trace( "2nd menu option was clicked for " + item.getData( "product" ) + "\r\n" );
		}
	]]>
	</klipscript>
</klip>

     	

To add custom menu options for specific items rather than to all of them, use Item.actions().

For custom menu options for the Klip Menu, use Items.globalactions().

Parameters:
text1 - text to display as a custom option in the menu
function1 - function associated with text1
text2 - text to display as a custom option in the menu
function2 - function associated with text2

---

clear

function clear( [<boolean> permanently] )

Clears all entries in the Items[] array (user will see an empty Klip).

Parameters:
permanently - true permanently destroys the items; otherwise, false places the cleared items in the Items.Deleted array.

---

findItemByIID

integer findItemByIID( <String> iid )

Returns the index of the item in the Items array that matches the specified iid.

Parameters:
iid - ID of the Item to search for in the Items[] array

Returns:
index of item (if found); otherwise, returns -1

---

globalactions

array globalactions( <String> text1, <function> function1[, <String> text2, <function> function2, ...])

Adds a custom menu option(s) above "Refresh" in the Klip Menu. Specify an array of pairs of text to display as a new option in the menu and an associated function.

Note:
The location of the custom menu option(s) is not configurable.

Example:
In this example, a new menu option 'Global Menu Option' is added in the Klip Menu.



<?xml version='1.0' ?>
<klip>
  <identity>
    <title>
       API - Items.globalaction
    </title>
  </identity>

   <locations>
      <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>
      item {
         type: item;
         definition: all;   
      }

      screenshot {
         itemcol: 1;
         noterow: 1;
         
         type: image;
         notelabel: false;
      }

      product {
         itemcol: 2;
         noterow: 2;
         notelabel: false;
      }
   </style>
  
<klipscript>
<![CDATA[

function onRefresh() {

        var success = Engines.Data.process(Prefs.contentsource);
	
  	setItemActions();

	return success;
}

// Add custom menu options
function setItemActions() {

	// Add menu option under Klip Menu
	Items.globalactions = [ "Global Menu Option", doThese ];
}

function doThese() {
	trace( "### Global Menu Option" + "\r\n");
}

]]>
</klipscript>
  
  
</klip>
     	

To add custom menu options for items rather than to the Klip Menu, use Items.actions().

For custom menu options for items that meet specific criteria, use Item.actions().

Parameters:
text1 - text to display as a custom option in the menu
function1 - function associated with text1
text2 - text to display as a custom option in the menu
function2 - function associated with text2

---

onClick

function onClick( [<integer> index], [<String> style] )

Specifies a Handler Function for Klipfolio Dashboard to call in your JavaScript when the user clicks on any item in the Klip.

Example:
The following Klip sends output to the Debug Window when the user clicks or deletes an item in a Klip.



<klip>
   <identity>
      <title>
         API: Items.onClick()
      </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()
{
    Items.onClick  = itemsOnClick;
    Items.onDelete = itemsOnDelete;
}

function onRefresh()
{
    Engines.Data.process ( Prefs.contentsource );
    return true;
}


//
// Support functions -----------------------------------------------
//

function itemsOnClick( index, style ) 
{
  trace( "You clicked on Item at Items[" + index + "] on the <" + style + "> column\r\n" );
}

function itemsOnDelete( index ) 
{
  trace( "You requested to delete Item at Items[" + index + "]\r\n" );

  return true;
}

   ]]>
   </klipscript>
</klip>

     	

If the user clicks the date of the second item and then deletes the first item (i.e. right-clicks on the item and chooses 'Remove'), Klipfolio Dashboard would display the following output in the Debug Window.


 You clicked on the <date> column of the Item at Items[1] 
 You requested to delete Item at Items[0]
 

Note: Notice the assignment to the handler function is itemsOnClick, not itemsOnClick(). The former is a function, while the latter is the return value from a function call.

Parameters:
index - the index of the clicked item in the Items[] array
style - the name of the clicked column

---

onDelete

boolean onDelete( [<integer> index] )

Specifies a Handler Function for Klipfolio Dashboard to call in your JavaScript when the user attempts to delete any item in a Klip.

Note: Klipfolio Dashboard calls event handlers only on user actions or Klip lifecycle events. Deleting an item by calling Items.onDelete() does not trigger this event handler.

See onClick() for an example of using onDelete.

Parameters:
index - the index of the requested deleted item in the Items[] array

Returns:
true indicates that Klipfolio Dashboard can delete this item; otherwise, if returns false, Klipfolio Dashboard will not delete this item. This handler is not intended to replace the Item.candelete property; rather, it is meant to allow special processing of deletion requests.

---

processAutoRemove

function processAutoRemove()

Requests Klipfolio Dashboard to immediately remove all items that are older than the user's Klipfolio Dashboard preferences setting.

The preferences settings refers to the setting for 'Automatically remove old items:' in the 'General' Tab of the Klipfolio Dashboard's Options window. Klipfolio Dashboard removes older items when Klip.onRefresh() returns a true.

If your Klip has a large number of items (say hundreds) and you intend to iterate through each one in an Klip.onRefresh() handler, then call Items.purge() near the top of the Klip.onRefresh() handler to immediately remove all those items that would have been removed after Klip.onRefresh() returns true, thus saving your Klip time processing items that would no longer visible to users.

---

purge

function purge( [<boolean> permanently] )

Removes all un-modified entries in the Items array at the end of the Klip.onRefresh() event.

The call to purge instructs Klipfolio Dashboard to immediately mark all items as un-modified. Klipfolio Dashboard then keeps all marked items that are modified or updated during the onRefresh() event handler. When your JavaScript reaches the end of an onRefresh(), Klipfolio Dashboard deletes all items that remain un-marked (these items were not added or updated during the current onRefresh).

This API call is usually used when creating a Dashboard Klip. See Items.autoremove for an example Klip that uses purge.

Use this function if you want to ensure the user sees only new or updated items after the next onRefresh.

Parameters:
permanently - true permanently destroys the items; otherwise, false places the purged items in the Items.Deleted array.

---

remove

boolean remove( <Item> item | <integer> index [, <boolean> permanently] )

Removes an existing item from the Klip.

Parameters:
item - Item object to remove
index - the index of the item to remove
permanently - true permanently destroys the item; otherwise, false places the removed item the Items.Deleted array.

Returns:
true if the item could be found and removed; otherwise, returns false

---

sort

function sort( <String> sortBy | <boolean> reversed )

Sorts items based on the specified sort option.

Valid sort options are:

"text"

Sort alphabetically in ascending order.

"pubdate"

Sort by pubdate property [high-low].

"creation"

Sort by creation property in ascending order. Klipfolio Dashboard assigns all new/updated items during an onRefresh() with the same creation timestamp. That means the first time the user loads the Klip, all items would have the same creation date.

"sequence"

Sort in the exact order in which items were created

"lastmodified"

Sort by lastmodified property [high-low].

"<name of a style>"

Sort this CSS style's column.

"<JavaScript comparator function"

See below.

Comparator Function:
If you specify a comparator function instead, the function must accept two Item objects and return a -1, 0, or 1, based on whether the first item provided should come before, is equal to, or should come after the second item. A comparator function typically uses Item.getData() on the Item objects to compare a properties of the Item object to determine return value.

Parameters:
sortBy - one of the following: text, pubdate, creation, sequence, lastmodified, style, or comparator function.
reversed - true to reverse sorting order

---

Overview   Object  Tree  Index  Help			Klipfolio Dashboard 5 API
PREV OBJECT  NEXT OBJECT	FRAMES    NO FRAMES
SUMMARY: PROPERTY | FUNCTION	DETAIL: PROPERTY | FUNCTION

---

© 2009 Klipfolio Inc. All Rights Reserved.