Prefs

The Prefs object provides an API to store and retrieve preferences between Klipfolio Dashboard sessions. Most often, these preferences will be information entered by the user into your UI components (such as a TextField) in the Klip's Customize window.

Use setPref() to store a preference as a named pair, as in

 
 Klip.setPref( "myURL", "http://www.serence.com/" )

and use getPref() to later retrieve it the value of the name, as in

 trace( "Value of: " + Klip.getPref( "myURL" ) + "\r\n" );

As stated, information you store using setPref() persist between sessions, but changing the Klip's internal preferences, such as with Prefs.refreshrate, is valid only for the current session. When Klipfolio Dashboard starts up again, it will revert to the value specified in the Klip.

You can achieve effect of making a change to Prefs.refreshrate permanent by storing the value in your own preference using setPref() and in the Klip's Klip.onLoad() handler function, retrieving the value and immediately assigning it to Prefs.refreshrate.

Example: Setting and Querying Preferences

The following Klip gives an example of setting and querying various preferences.

<klip>
   <identity>
      <title>
         API: Prefs
      </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() {
 
    //
    // Set three preferences
    //
    Prefs.setPref( "pref_A", "23" );
    Prefs.setPref( "pref_B", "true" );
    Prefs.setPref( "pref_C", "http://www.klipfolio.com" );
    
    //
    // Dump Prefs (method #1)
    //
    trace( "Value of pref_A: '" + Prefs.getPref( "pref_A" ) + "'\r\n" );
    trace( "Value of pref_B: '" + Prefs.getPref( "pref_B" ) + "'\r\n" );
    trace( "Value of pref_C: '" + Prefs.getPref( "pref_C" ) + "'\r\n" );  
    
    //
    // Update the preferences
    //
    trace( "\r\n" );
    trace( "Setting pref_A, pref_B, and pref_C.\r\n" );
    Prefs.setPref( "pref_A", "1000" );
    Prefs.setPref( "pref_B", "false" );
    Prefs.setPref( "pref_D", "A New Pref" );
    
    //
    // Dump all Prefs (method #2) 
    //
    trace( "\r\n" );
    show_all_prefs();
    
    //
    // Check the value of pref_B
    //
    trace( "\r\n" );
    trace( "First Check: " );
    if( Prefs.getPref( "pref_B" ) == "true" ) {
        trace( "Pref_B is true\r\m" );
    } else {
        trace( "Pref_B is false\r\n" );
    }
    
    //
    // This is a common idom to convert a pref's value (which is string) into a boolean
    // true or false.
    //
    var check_B = (Prefs.getPref( "pref_B" ) == "true" ? true : false );
    
    //
    // Check the value of pref_B again using check_B as a boolean
    //
    trace( "\r\n" );
    trace( "Second Check: " );
    if( check_B ) {
        trace( "Pref_B is true\r\n" );
    } else {
        trace( "Pref_B is false\r\n" );
    }
 
    //
    // When you query an non-existent preference, Klipfolio Dashboard returns 
    // the empty string.
    //
    trace( "\r\n" );
    trace( "Querying values of pref_a and pref_X\r\n" );
    trace( "Value of pref_a: '" + Prefs.getPref( "pref_a" ) + "'\r\n" );
    trace( "Value of pref_X: '" + Prefs.getPref( "pref_X" ) + "'\r\n" );
    
    
    //
    // This is another common idom: check for a preference to see if this is the
    // first time this Klip is loaded.
    //
    trace( "\r\n" );
    if (Prefs.getPref ("preconfigured") != "true")
    {
        // ... setup your prefs, default values for UI components, etc.
 
         //
         // Don't do KlipSetup next time this Klip Loads
         //
        Prefs.setPref ("preconfigured", "true");
    }
 
 }
 
 function onRefresh()
 {
    var xml = "<xml><item><link></link><description>" +
          "(See Debug Window for output)" +
          "</description></item></xml>";
             
     return Engines.Data.process( xml );
 }
 
 //
 // Iterate through your Klip's prefs by accessing Prefs[] as an array
 //
 function show_all_prefs() {
    var i;
    for (i = 0; i < Prefs.length; i++) { 
       trace("Prefs["+i+"] '"+Prefs[i].name+"' == '"+Prefs[i].value+"'\r\n"); 
    }
}


   ]]>
   </klipscript>
</klip>

Upon loading, Klipfolio Dashboard will display the following output in the Debug Window.

 Value of pref_A: '23'
 Value of pref_B: 'true'
 Value of pref_C: 'http://www.serence.com'
 
 Setting pref_A, pref_B, and pref_C.
 
 Prefs[0] 'pref_A' == '1000'
 Prefs[1] 'pref_B' == 'false'
 Prefs[2] 'pref_C' == 'http://www.serence.com'
 Prefs[3] 'pref_D' == 'A New Pref'
 
 First Check: Pref_B is false
 
 Second Check: Pref_B is false
 
 Querying values of pref_a and pref_X
 Value of pref_a: ''
 Value of pref_X: ''

Properties Summary
`integer`	`codepage` Returns the value of the `<refresh>` element specified in the .klip file.
`String`	`contentsource` Returns the value of the `<contentsource>` element specified in the .klip file.
`String`	`defaultlink` Returns the default link activated when a user clicks on your Klip's icon.
`double`	`firstinstall` Returns the timestamp (in seconds) when this instance of the Klip was first added to Klipfolio Dashboard (read-only).
`double`	`lastrefresh` Returns the timestamp (in seconds) when the Klip last returned `true` from its Klip.onRefresh() handler (read-only).
`integer`	`length` Returns the length of the items in the Prefs collection.
`String`	`loading` Returns the value of the `<loading>` element specified in the .klip file (write-only).
`String`	`nodata` Returns the value of the `<nodata>` element specified in the .klip file (write-only).
`integer`	`referer` Returns the value of the `<referer>` element specified in the .klip file (read-only).
`integer`	`refreshgranularity` Specifies the number of seconds (default 60) for each count in Prefs.refreshrate.
`integer`	`refreshrate` Returns the value of the `<refreshrate>` element specified in the .klip file.
`String`	`title` Returns the value of the `<title>` element specified in the .klip file (write-only).
`integer`	`uniqueid` Returns the value of the `<uniqueid>` element specified in the .klip file (read-only).

Function Summary
`boolean`	`delPref( <String> name )` Deletes the persistent preference associated with `name`.
`function`	`getContent( <String> content_tag_name )` Returns the value of specified element within `...` tags which can store multiple stylesheets.
`String`	`getPref( <String> name )` Returns the value associated with the preference `name`.
`function`	`setPref( <String> name, <String> value )` Stores `name` as a persistent preference with the value `value`.

Properties Detail

codepage

integer codepage

<refresh>

This value specifies the codepage currently in use for encoding text processed by this Klip.

Example: Querying Klip's Parameters
The following Klip sample settings for those elements that are available for querying from JavaScript.

<klip>
   <identity>
      <title>
         API: Prefs.codepage
      </title>
      <uniqueid>
        api_prefs-codepage_sample12345
      </uniqueid>
   </identity>
   <locations>
      <defaultlink>
        http://www.klipfolio.com/
      </defaultlink> 
      <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>
   <setup>
     <refresh>
       120 
     </refresh> 
     <codepage> 
       1252
     </codepage>
   </setup>
   <messages>
     <loading>
       Please wait, getting data...
     </loading> 
     <nodata>
       No items to display.
     </nodata> 
   </messages>
   <klipscript>
   <![CDATA[

function onLoad() {

    trace( "Querying read-only prefs:\r\n" );
    trace( "  Prefs.contentsource : " + Prefs.contentsource + "\r\n" );
    trace( "  Prefs.referer       : " + Prefs.referer + "\r\n" );
    trace( "  Prefs.codepage      : " + Prefs.codepage + "\r\n" );
    trace( "  Prefs.lastrefresh   : " + Prefs.lastrefresh  + "\r\n" );
    trace( "  Prefs.uniqueid      : " + Prefs.uniqueid  + "\r\n" );

    trace( "\r\nQuerying read/write prefs:\r\n" );   
    trace( "  Prefs.refreshrate   : " + Prefs.refreshrate + "\r\n" );
    trace( "  Prefs.defaultlink   : " + Prefs.defaultlink + "\r\n" );

    Prefs.refreshrate = 60;
    Prefs.defaultlink = "http://www.klipfolio.com/";

    trace( "\r\nAfter update:\r\n" );   
    trace( "  Prefs.refreshrate   : " + Prefs.refreshrate + "\r\n" );
    trace( "  Prefs.defaultlink   : " + Prefs.defaultlink + "\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>

 Querying read-only Prefs:
   Prefs.contentsource : http://www.serence.com/support/samples/demo/demo-static.xml
   Prefs.referer       : undefined
   Prefs.codepage      : 1252
   Prefs.lastrefresh   : 0
   Prefs.uniqueid      : undefined
 
 Querying read/write Prefs:
   Prefs.refreshrate   : 120
   Prefs.defaultlink   : undefined
 
 After update:
   Prefs.refreshrate   : 60
   Prefs.defaultlink   : http://www.klipfarm.com/farm.php

contentsource

String contentsource

<contentsource>

defaultlink

String defaultlink

Returns the default link activated when a user clicks on your Klip's icon.

firstinstall

double firstinstall

lastrefresh

double lastrefresh

true

Klip.onRefresh()

length

integer length

loading

String loading

<loading>

This value specifies the text message to display when the Klip has no data to display and is processing any JavaScript.

nodata

String nodata

<nodata>

This value specifies the text message to display when the Klip has no data to display and is not processing any JavaScript.

referer

integer referer

<referer>

refreshgranularity

integer refreshgranularity

Prefs.refreshrate

This parameter enables a Klip to refresh faster than once a minute. For example, if the value of Prefs.refreshrate is 1, then setting

    Prefs.refreshgranularity = 10;

Note: This parameter is not available in Klipfolio Personal Dashboard.

refreshrate

integer refreshrate

<refreshrate>

This value specifies how many minutes Klipfolio Dashboard should wait before sending the Klip an onRefresh event (see Klip.onRefresh()).

title

String title

<title>

uniqueid

integer uniqueid

<uniqueid>

Function Detail

delPref

boolean delPref( <String> name )

name

Parameters:

name

Returns:

true

false

getContent

function getContent( <String> content_tag_name )

...

Example:

<content>
	<style1>
		...
	</style1>
	<style2>
		...
	</style2>
</content>
...
engines.KlipFood.stylesheet = Prefs.getContent("style1");

Parameters:

content_tag_name

tags.

getPref String getPref( <String> name ) Returns the value associated with the preference name. See setPref(). Example: The following function sets two preferences and queries their value. <klip> <identity> <title> API: Prefs.getPref() </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() { Prefs.setPref( "userQueryString", "Klipfolio, Klipfolio Dashboard, Klips" ); Prefs.setPref( "userRefreshRate", "30" ); trace( "Klip's stored preferences: \r\n" ); trace( " userQueryString : " + Prefs.getPref( "userQueryString" ) +"\r\n" ); trace( " userRefreshRate : " + Prefs.getPref( "userRefreshRate" ) +"\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> Upon loading, Klipfolio Dashboard will display in the Debug Window: Klip's stored preferences: userQueryString : Klipfolio, Klipfolio Dashboard, Klips userRefreshRate : 30 Parameters: name - case-sensitive name of the preference to retrieve. Returns: the value associated with the preference name. If no preference exists for the given name, returns empty string. setPref function setPref( <String> name, <String> value ) Stores name as a persistent preference with the value value. Klipfolio Dashboard will store the contents of the preference exactly, including whitespace. See getPref(). Note Note that Prefs.setPref() always stores a string, and Prefs.getPref() always returns a string. Be aware that Prefs.setPref() will convert any parameter to a string. For example, if you try to store a boolean value, it will store the string true or false, and Prefs.getPref() will return a string. If you want return a boolean, you'll need to convert it, as in the following example: var check_B = (Prefs.getPref( "pref_B" ) == "true" ? true : false ); Parameters: name - case-sensitive name of the preference to store. value - value of the preference to store. 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.

Object Prefs

Example: Setting and Querying Preferences

codepage

contentsource

defaultlink

firstinstall

lastrefresh

length

loading

nodata

referer

refreshgranularity

refreshrate

title

uniqueid

delPref

getContent

getPref

setPref