While discussing the basic Klip development steps in the previous chapter, the use of the <klipscript> block was not covered at all. This is because the default functionality of the internal data parsing engines was sufficient to display data in the basic Klip. By simply providing the URL of the data source in the <contentsource> block, those internal engines took care of the entire process from accessing to retrieving the data. However, you may run into situations in which you will want to supplement or override the default behaviour of those engines.
Klipfolio Dashboard has a built-in JavaScript interpreter that lets you extend and override its built-in logic, enabling you to create Klips that can, for example, access data from any web-based application and process the data before it is displayed to the user.
Klipfolio Dashboard implements an event-driven model. This means you define your own JavaScript functions in a Klip that the application calls when specific events occur. It exposes the contents and logic of a Klip through an application programming interface (API) that is visible as JavaScript objects. You can view the full documentation for Klipfolio Dashboard's API online.
When the need arises for you to implement your own functions using the Klipfolio Dashboard APIs, it is important to know how a Klip's life cycle works.
When Klipfolio Dashboard executes a Klip, there are four distinct phases for the Klip's life cycle.
Phase 1: Load Klip — Load the Klip's source into memory. This occurs when a Klip is added to Klipfolio Dashboard, i.e. it is saved in the myklips folder.
Phase 2: Load Settings — Retrieve the Klip's settings, if available. The application keeps track of all of the Klip's settings in a corresponding .prefs.xml file, located in the settings folder.
If the Klip is added for the first time, Klipfolio Dashboard creates a settings file for it.
The settings for each Klip include:
Size and position of the Klip within the dashboard.
Customizations made to the Klip by the user, such as whether to display column headers, whether and what filters were applied, and whether or not the Klip is visible or hidden in the dashboard.
Current and previous items displayed in the Klip over the past seven (7) days.
Phase 3: Execute — Respond to incoming events from the user and the application. While there are many types of events, the most common event is the refresh event which can be triggered when:
Klipfolio Dashboard loads the Klip.
The refresh interval defined in <refresh> occurs.
The user clicks the button in the dashboard's toolbar
The user refreshes an individual Klip.
It is in this step that the application executes any JavaScript that you have added.
Phase 4: Save Settings — Save the Klip's settings to disk. The settings file is saved about a minute after any changes are made to the Klip's settings and whenever Klipfolio Dashboard exits.
The figure below shows the four phases of a Klip's life cycle.
Phase 3 is where Klipfolio Dashboard executes your JavaScript.
