A Simple Twitter App written in KPS: What's Happening?

                    
Why XML?
XML is a great tool for describing data, for declaring the structure of objects- and everyone knows XML. KPS uses XML for the structure of apps. This common structure makes the code easier to read, and inherently modular. This in turn encourages more code sharing and easier code maintenance. It allows developers to isolate parts of the code and manage them independently. It also enables tools to easily operate on KPS applications, such as the outline view navigator in KDT (as shown at right).  What XML does not do well is describe logic: for that KPS embeds ECMAScript (aka JavaScript).

					
<?xml version="1.0" encoding="utf-8"?>

<application xmlns="http://www.kinoma.com/kps/1" id="com.kinoma.whatshappening" version="1.0">
Interacting with Kinoma Play's Homescreen
The Service element defines the entry point into the app.  The Title and Icon given here will determine how the app is listed on the Kinoma Play homescreen.  The Action parameter selects which Handler will be invoked when the user launches the app.
  <service title="What's Happening?" icon="locate" action="/main"/>
Icons
Icons are loaded from icon strips and made available throughout the app.  They are referenced by name in Viewers to render the icon and to bind data records to interface elements (as explained below).  Developers can provide icon strips at small, medium, and large resolutions.  Kinoma Play automatically chooses the icon size that is most appropriate for the user's display.
  <icons small="small.png" medium="medium.png" large="large.png" names="trend,locate" />
Data Retrieval and Processing in Handlers
KPS handlers are roughly analogous to web server handlers, such as an Apache plug-in or a PHP script: they are triggered by a URI, their behavior may be modified by query parameters, they operate asynchronously, and they usually return some data or redirect to another URI. KPS handlers retrieve and parse data from various services and manipulate it into a format that KPS uses to construct the user interface.  The Handler creates and returns an object, usually a List, that represents the items to be displayed on screen.  To do this, the Handler can redirect requests to other Handlers within the app, services provided by KPS, or external web services.
  <handler id="main">
    <script><![CDATA[
        function onQuery(query){
          this.loadHTTP("http://api.twitter.com/1/trends/1.json");
        }
Asynchronous Loading
Like web services, KPS Handlers often operate asynchronously. KPS even provides a default progress indicator while retrieving data asynchronously. A handler is initially invoked through its onQuery() function.  onQuery() can directly return data to be displayed by a Viewer, or it may initiate an asynchronous request for data.  When the response from the data retrieval request is received, KPS invokes the handler’s onResponse() function which processes the data for display by a Viewer.
        function onResponse(response, query, link){
          var reply = response.parseJSON();
   				
          var trends = reply[0].trends;   				
          var data = this.createList();
          record = this.createRecord("", "label", "Trending Topics");
          data.addRecord(record);

Interface Elements are List Records
Many KPS Handlers return a simple list of records that represent what should be displayed.  List records are used to specify both data-driven UI elements and user interface tools, such as separators, buttons, and icons.  This example builds a list that contains one record for each of the first five Twitter trends, visual separator records, and records that function as buttons to move to other features of the app.
          for (var i = 0; i < trends.length && i < 5; i++){
            var trend = trends[i];
            var record = this.createRecord("/search?search_term=" + trend.query, "trend", trend.name);
            data.addRecord(record);
          }

          record = this.createRecord("", "separator");
          data.addRecord(record);  

          record = this.createRecord("/SEARCH", "search", "Search Twitter");
          data.addRecord(record);

          record = this.createRecord("", "separator");
          data.addRecord(record);

          record = this.createRecord("/nearby", "near", "Show Nearby Tweets");
          data.addRecord(record);

          record = this.createRecord("", "separator");
          data.addRecord(record);
               
          return data;
        }            
      ]]></script>
  </handler>

Building the UI in Viewers
Viewers transform the records built by handlers into a user interface by binding records to display elements. Viewers are optional – KPS provides a simple default viewer. A common way to build a KPS application is first to implement the data flow using only Handlers with the default Viewer, and then add Viewers to refine the user interface. App developers have access to a wide range of user interface tools built into KPS, and can customize all of them. In addition, developers can build entirely new controls in KPS. 


  <viewer id="main">
    <layout>
      <table>
Mapping Records to UI Elements
Each record in a List specifies an icon type.  The icon property has two roles: it specifies the binding between record types and display types, and it provides the default icon for the Viewer to display for the record.   KPS uses the icon to map each record in a List created by the Handler to a Cell in the Viewer. Cells describe how to render their associated Records. Many Cells, such as the cells in this Viewer, describe their rendering using a simple XML layout language. When more precise control is required, Cells use scripts to describe the rendering of records, as is done in the Search Viewer below.
 


        <cell icon="tweet">
          <thumbnail style="middle"/>
          <column>            
            <text id="description" style="medium,bold,top" />       
            <text id="title" style="medium,bottom" lines="all" />
          </column>
        </cell>

        <cell icon="trend">
          <icon style="large,left" />
          <text id="title" style="medium,middle" />
        </cell>

        <cell icon="separator" select="false">
          <separator />
        </cell>

        <cell icon="label" select="false">
          <text id="title" style="large,bold,center" />
        </cell>

        <cell>
          <text id="title" style="black,left" />
        </cell>
      </table>
    </layout>
  </viewer>