You want to learn about the basic steps for writing your own Klip.
This article describes the very basics of Klip development.
If this is your first time using Klipfolio Dashboard, you might first want to familiarize yourself with the components of Klipfolio Dashboard and Klips. (See Klipfolio Dashboard and Klip fundamentals)
The common steps to displaying data in a Klip are as follows:|
Table of Contents
|
Be sure to reload the Klip as you add new changes to see how they are reflected and to correct any mistakes.
In this article, we will go through each step using sample XML source in Klipfolio Dashboard Developer Edition. An overview of the Developer Edition toolbar and Klip controls mentioned below can be found at http://developer.klipfolio.com/developer/deved-guide.
Click the New button in the toolbar, then select Blank Klip.
A blank Klip is added to the dashboard. At this point, the Klip should look stale (i.e. darker than a Klip that has data in it) because it cannot access its data source. This is because we haven't specified the location of the data source, yet.
Click the View source button in the Klip's title bar, or from the Klip's menu, select "View source".
For this example, we will use a simple XML file located at http://support.klipfolio.com/files/demo/demo.xml as the Klip's data source. How-to articles discussing specific requirements for various types of data sources can be found under the Retrieving Data section of the how-to articles list.
Inside the <contentsource> tag, add http://support.klipfolio.com/files/demo/demo.xml:
<html>
<contentsource>
http://support.klipfolio.com/files/demo/demo.xml
</contentsource>
</html>Save and reload the Klip by clicking the Reload button in its title bar. You will still see "No data" in the Klip because we have not updated the <style> block to match the tags in data source -- the Klip doesn't know what to extract from the source file nor how to display it. However, now that the Klip can access its data source, it should no longer look stale.
Next, we will update the <style> section to start displaying the content in the Klip.
Each Klip needs to have a stylesheet that matches its data source. Only what you specify in the <style> block will be reflected by the Klip. Before you start writing this block, you should take a look at the data source, identify where one set of information (we call this an item) starts and ends, and decide what parts of the set you want to display in your Klip. In the Klip, one item will be displayed as one row. If you have 3 items, you will have 3 rows in your Klip.
For example, our sample data at http://support.klipfolio.com/files/demo/demo.xml is made up of pairs of tags containing contents as follows:<html>
<alerts>
<alert>
<level>...</level>
<sender>...</sender>
<summary>...</summary>
<date>...</date>
<category>...</category>
<url>...</url>
<id>...</id>
</alert>
<alert>
<level>...</level>
...
</alert>
</alerts>
</html>This means that an item starts from <alert> and ends at </alert>.
<style>
alert {
type: item;
}
</style>Reload the Klip. The Klip still says "No data" because we haven't specified what data in the item to display and where to display it.
Let's say you want to display the contents of <level>...</level>, <sender>...</sender>, <summary>...</summary>, and <date>...</date> in the 1st, 2nd, 3rd, and 4th columns, respectively. To do so, we use the CSS property itemcol: <desired column>.
<style>
alert {
type: item;
}
level {
itemcol: 1;
}
sender {
itemcol: 2;
}
summary {
itemcol: 3;
}
date {
itemcol: 4;
}
</style>When you save and reload the Klip, it should look like this.
...
level {
itemcol: 1;
type: image;
}When you reload the Klip, its content should look like this:
If not, double-check for mistakes such as typos and missing semi-colons and reload the Klip.
For a complete list of supported content types, see Appendix A of the Klip Developer Guide.
Settings that apply to the entire Klip are specified above the <style> block. The blank Klip we are working on includes several empty tags that are most commonly used. Go through and update them with your information.
Of the most commonly used XML parameters used in the template Klip, <kliplocation> and <version> (in the <identity> block) deserve special attention.
Klipfolio Dashboard has a build-in mechanism that periodically checks for Klip upgrades at <kliplocation> as long as the automatic Klip Upgrades is turned on under Options. When this occurs, the application compares the <version> set in the Klip at <kliplocation> against that of the Klip in the local myklips folder. It is important to always keep the latest copy of your Klip at kliplocation or none at all to ensure that the users only get notified for the upgrades you intend for them to get. If the <version> of the local Klip is different from the one at the Klip location, users will be prompted to upgrade.
Be sure to set it to the URL at which you plan to place your Klip(s) including its name. For example:<html>
<kliplocation>
http://www.klipfolio.com/klips/myKlip.klip
</kliplocation>
</html>It is worth nothing that if you do not set <kliplocation> for your Klips, you will need to let your users know about the availability of a new version some other way, such as by email.
There are many other XML parameters not included in the blank Klip that you might find useful, such as <purge> and <columns>. See Klip Developer Guide for a complete list of XML parameters and their details.
One of the many improvements you can make to a Klip is to use a tooltip. A tooltip is displayed when a user hovers over individual items in a Klip. In the tooltip, you can choose to include or exclude the content shown in the Klip itself. You can also display content that is not shown in the Klip itself. The latter is useful when you have a lot of information that you cannot or do not want to include in the Klip but still want the users to be able to see.
To show content in the tooltip, use the noterow property.
For example, perhaps you want to show in your tooltip everything shown in the Klip except the <level>, plus the <id>. Try updating your Klip to match the following stylesheet, reload it, and hover over each item to see how the changes are reflected in the tooltip:
<style>
alert {
type: item;
}
level {
itemcol: 1;
type: image;
}
sender {
itemcol: 2;
noterow: 1;
notelabel: false;
emphasis: strong;
}
summary {
itemcol: 3;
noterow: 4;
}
date {
itemcol: 4;
noterow: 3;
}
id {
noterow: 2;
label: "id #";
}
</style>
<setup>
...
<columns>
true
<columns>
</setup>To specify the labels for the column headers, use the collabel property.
Once you are comfortable with writing a basic Klip that displays your own data, think of how it can be presented better by using numerous features available in Klipfolio Dashboard. For example, you might like to display graphic indicators for your numeric data to give it more context at a glance, or use mathematical formulas in the Klip itself to manipulate it. Or perhaps you'd like your users to be able to drill down different levels of information instead of scrolling down 200 rows of data that share a number of same categories.
For tips on how to do these and more, check out other how-to articles, Klip Templates and Samples, and other resources available at http://developer.klipfolio.com.
