Object
   |
   +--Item

The Item object is the direct API to access the properties of individual item contained within the Items object or Items.Deleted object.

---

Properties Summary
boolean	alerting           Specifies whether this item is highlighted and causing the Klip to alert.
boolean	autoremove           Specifies whether the item may be removed automatically due to the user's Klipfolio Dashboard preferences setting for Auto Remove (default true).
boolean	candelete           Specifies whether this item can be deleted by a user.
boolean	canpurge           Specifies whether this item can be purged after an Klip.onRefresh() has completed.
boolean	canvisit           Specifies whether this item becomes visited when a user clicks on it (or dismisses all items in the Klip).
double	creation           Specifies UNIX Epoch timestamp (in seconds) of when the item was created.
String	getDataCount           Returns the number of data elements for iteration or index access using Item.getData().
boolean	hidden           Specifies whether this item is hidden (not visible) to the user.
double	lastmodified           Specifies UNIX Epoch timestamp (in seconds) of when the item was last modified.
boolean	recent           Returns true if this item was added/modified during the last refresh.
boolean	visited           Specifies whether this item appears visited (dimmed).

   

Function Summary
array	actions( text1, function1[, text2, function2, text3, function3, ...])            Adds a custom menu option(s) above "Copy" in the menu that appears when the user right-clicks on individual items in a Klip.
function	getData( name [, <integer> n] | <integer> index )            Gets the data element of an Item.
function	hasData( <String> property )            Returns true if the property exists in the Item and has data.
function	onClick( [<integer> index] )            Specifies a Handler Function to call when the user clicks on this item.
function	onDelete( [<integer> index] )            Specifies a Handler Function to call when the user attempts to delete this item.
function	setData( <String> name, <String> value [, <integer> n] | <integer> index, <String> value1 )            Sets a data element an Item.

Properties Detail

alerting

boolean alerting

Specifies whether this item is highlighted and causing the Klip to alert.

---

autoremove

boolean autoremove

Specifies whether the item may be removed automatically due to the user's Klipfolio Dashboard preferences setting for Auto Remove (default true).

You can override individual autoremove settings using Items.autoremove.

---

candelete

boolean candelete

Specifies whether this item can be deleted by a user.

---

canpurge

boolean canpurge

Specifies whether this item can be purged after an Klip.onRefresh() has completed.

---

canvisit

boolean canvisit

Specifies whether this item becomes visited when a user clicks on it (or dismisses all items in the Klip).

---

creation

double creation

Specifies UNIX Epoch timestamp (in seconds) of when the item was created.

---

getDataCount

String getDataCount

Returns the number of data elements for iteration or index access using Item.getData().

---

hidden

boolean hidden

Specifies whether this item is hidden (not visible) to the user.

Hidden items are completely inaccessible to the users and do not trigger alerts.

---

lastmodified

double lastmodified

Specifies UNIX Epoch timestamp (in seconds) of when the item was last modified.

---

recent

boolean recent

Returns true if this item was added/modified during the last refresh.

Setting recent to true also sets lastModified() to true.

---

visited

boolean visited

Specifies whether this item appears visited (dimmed).

---

Function Detail

actions

array actions( text1, function1[, text2, function2, text3, function3, ...])

Adds a custom menu option(s) above "Copy" in the menu that appears when the user right-clicks on individual items 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.

This function is useful when you have specific items in a Klip (but not all items) for which you want to add an additional menu option.

Example:
In this example, only the items that contain the word 'Utopia' will display a custom menu option.



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

   <locations>
      <contentsource>
         http://www.serence.com/support/samples/definition_example.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>
      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 for a specific item
	var i = 0;
	for(i = 0; i < Items.length; i++)
	{
		if(Items[i].getData("product").indexOf("Utopia") != -1)
		{
			Items[i].actions = ["Option for Specific Item", doIt ];
		}
	}

}

function doIt(item)
{
	trace("Menu option was clicked!\r\n");
}

]]>
</klipscript>
  
  
</klip>
     	

To add custom menu options that apply to all items in your Klip, use Items.actions().

To add menu options to the Klip Menu, use Items.globalactions().

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

---

getData

function getData( name [, <integer> n] | <integer> index )

Gets the data element of an Item.

This function can take one of three possible sets of parameters:

name

Returns value of first property matching "name", or false if no match found.

name, n

Returns value of the nth property matching "name", or false if no match found.

index

Returns value of property at index, or false if no match found.

Parameters:
n - nth property
index - index of property
property - name of property

---

hasData

function hasData( <String> property )

Returns true if the property exists in the Item and has data.

Parameters:
property - name of property

Returns:
true if the property exists in the Item and has data

---

onClick

function onClick( [<integer> index] )

Specifies a Handler Function to call when the user clicks on this item.

If your handler function returns false, Klipfolio Dashboard will not set the item to the visited state to true and dim the item.

Specifying a handler function for a specific Item overrides any global Items.onClick() handler function (which applies to all items in the Klip). This handler is not intended to replace the Item.canvisit property; rather, it is meant to allow special processing of item click actions.

Example:
The following sample Klip assigns an individual handler function to the first and second item.



<klip>
   <identity>
      <title>
         API: Item.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 onRefresh()
{
    Engines.Data.process ( Prefs.contentsource );

    Items[0].onClick  = firstOnClick;
    Items[1].onClick  = secondOnClick;

    return true;
}


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

function firstOnClick( index ) 
{
  trace( "firstOnClick: You clicked on item " + index + "\r\n" );
}

function secondOnClick( index ) 
{
  trace( "secondOnClick: You clicked on item " + index + "\r\n" );

  return true;
}

   ]]>
   </klipscript>
</klip>
     	

If the user clicks the first item, then second item, this Klip will output the following to the Debug Window.


 firstOnClick: You clicked on item 0
 secondOnClick: You clicked on item 1
 

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

Parameters:
index - of the item in the Klip that the user clicked on

---

onDelete

function onDelete( [<integer> index] )

Specifies a Handler Function to call when the user attempts to delete this item.

Specifying a handler function for a specific Item overrides any global Items.onDelete() handler function (which applies to all items in the Klip). If your handler function returns false, Klipfolio Dashboard will not delete the item.

This handler is not intended to replace the Item.candelete property; rather, it is meant to allow special processing of deletion requests.

Example:
The following assigns an individual handler function to the first and second Item.



<klip>
   <identity>
      <title>
         API: Item.onDelete()
      </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()
{
    Engines.Data.process ( Prefs.contentsource );

    Items[0].onDelete  = firstOnDelete;
    Items[1].onDelete  = secondOnDelete;

    return true;
}


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

function firstOnDelete( index ) 
{
  trace( "firstOnDelete: You clicked on item " + index + "\r\n" );
}

function secondOnDelete( index ) 
{
  trace( "secondOnDelete: You clicked on item " + index + "\r\n" );

  return true;
}

   ]]>
   </klipscript>
</klip>
     	

If the user clicks the first item, then second item, this Klip will output the following to the Debug Window.


 firstOnDelete: You clicked on item -1
 secondOnDelete: You clicked on item -1
 

Note: The index refers to the items current position in the Items array. Furthermore, Klipfolio Dashboard does not open the URL for the Item (as defined in the CSS) until after the onClick handler function returns.

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

Parameters:
index - the index of the item in the Klip to be deleted

---

setData

function setData( <String> name, <String> value [, <integer> n] | <integer> index, <String> value1 )

Sets a data element an Item.

This function can take one of three possible sets of parameters:

name, value

Sets the value of the first property with name matching "name" to "value", returns true if property was set.

name, value, n

Sets the nth value of the first property with name matching "name" to "value", returns true if property was set.

index, value1

Sets the value of property at index to "value1", returns true if property was set.

Parameters:
name - name of property
value - new value
n - nth property
index - index of property
value1 - name of property

---

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.