The "using XML" and "using JavaScript" are just names. The pairs of Klips are designed to do exactly the same thing in two different ways. This is to show developers examples of how to get from A to B with XML or with JavaScript.
Perhaps this would clarify the difference better -- the more descriptive names for the sample Klips "using XML" and "using JavaScript" would be:
- Sample Klip using XML parameters to get the data by specifying static information
- Sample Klip using JavaScript to get the data by specifying the same information as the XML version but with the flexibility to dynamically change any part of the data retrieval process using JavaScript
Why are there two versions?
For every type of data source that Klipfolio Dashboard supports, there are APIs for specifying its location, sending a request to the server, getting the data, and returning it to the Klip so it can displayed using its stylesheet. This is written in JavaScript in the <klipscript> block, and the sample Klips "using JavaScript" use this method.
However, for some of the source types, you can use the <contentsource> parameter to specify the source location instead. This parameter is essentially a shortcut to all that you would otherwise need to write out in JavaScript. By using <contentsource>, you are letting the default functionality of the application's internal engines take care of the above-mentioned process. This is the method used in the sample Klips "using XML".
Which type should I use?
To decide, consider the following.
Sample Klips using XML
- You simply update the information in the <contentsource> block. Klipfolio Dashboard uses that information to get the data from your database in XML, and displays it according to your stylesheet.
- Once written, you cannot change the content source information dynamically. Use this version if your data source location and query will remain static throughout the use of the Klip.
- This version does not provide you with an option to output errors and debug statements into the Debug Window.
- This version does not permit manipulation of the data itself.
Sample Klips using JavaScript
- The sample Klips include JavaScript templates of the entire process for setting the location of the data source, sending a request to the server, getting the data, to returning it to the Klip in XML format using the relevant APIs.
- You can monitor the errors in the <klipscript> using traceln and other developer tools.
- You can output in the Debug Window the returned data in XML format, which is very useful for referencing while customizing the <style> block.
- You have the option to dynamically change any part of the data retrieval process up to the point at which the data is returned to the Klip for display. Examples of such cases include, but are not limited to: when you want to allow users to enter a query string on demand, and when you want to merge data from more than one data source.
- At a minimum, you only need to update the same amount of information as you would with the samples using XML, but with the added benefits mentioned above.
Remember that, regardless of which type you use, you still need to customize the <style> block to specify how to display the retrieved data. For more information on the general steps of writing a Klip, see Klip development fundamentals.
Be sure to also refer to the relevant how-to article on the type of data you are working with.
