Klipfolio Dashboard is driven by events, and both the users and the application can trigger events in a Klip.

When an event occurs, the application spawns a thread of execution for the Klip. While each Klip is single threaded — there is only one thread of execution in a Klip at any given time — Klipfolio Dashboard is multi-threaded and can therefore update many Klips at the same time.

As you saw in the previous chapter, if a Klip does not contain any JavaScript, the application handles events directly using its built-in logic. For example, the application opens the URL in the Klip's <contentsource> parameter, retrieves the data, parses it, and displays the results in the Klip every time a refresh event occurs.

The following figure summarizes this behaviour.

Figure 3.2. Responding to Events (without JavaScript)

If the Klip contains JavaScript, the application looks to call a corresponding event handler within the <klipscript> block for an event.

If the Klip has the <klipscript> block in it, it must implement the onRefresh() event handler at the minimum. Another common event handler is onLoad(), which is called when the application first runs your Klip during each session.

The figure below demonstrates how the application calls various event handlers.

Figure 3.3. Responding to Events (with JavaScript)

To see how the dashboard calls the onLoad() and onRefresh() event handlers when the Klip loads, create a new Klip file with the following code.

                
<klip>
   <identity>
      <title>
         Klipfolio Dashboard Events
      </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>
   <klipscript>
      <![CDATA[

function onLoad() {
   traceln( "onLoad() -- " + Date() );
}

function onRefresh() {
   traceln( "onRefresh() -- " + Date() );

   return true;
}
      ]]>
      </klipscript>
      </klip>

When this Klip is loaded, you will see the following output in its Debug Window:

Figure 3.4. Debug Window

When you run this Klip, you will notice that it does not display anything. This is because it did not process any data, as the <contentsource> parameter was not included.

You can also assign your own onRefresh() handler as follows:

                
Klip.onRefresh = myOnRefresh; 

function myOnRefresh() { 
  traceln( "Inside myOnRefresh ..." );

   // your code here
}
                

As a side note, the example above worked because all functions in JavaScript run in global scope with the Klip object as root. Technically speaking, when your JavaScript defines function myfunction {...}, you are actually saying Klip.myfunction = function {...} as far as the application is concerned.