Overview   Objects  Tree  Index  Help 
Klipfolio Dashboard 5.0 API
 PREV OBJECT  NEXT OBJECT FRAMES    NO FRAMES    
SUMMARY: PROPERTY | FUNCTION DETAIL: PROPERTY | FUNCTION

Object Engines.HTTP.HTTPRequest

Object
   |
   +--Klip
         |
         +--Engines
               |
               +--Engines.HTTP
                     |
                     +--Engines.HTTP.HTTPRequest

Created by Engines.HTTP.newRequest(), an Engines.HTTP.HTTPRequest sets the parameters for an HTTP request to a remote web server and gives access to the reply.

The HTTPRequest object gives you fine-grain control over the HTTP request. This control lets you

When you call Engines.KlipFood.process() with a URL, Klipfolio Dashboard automatically creates an Engines.HTTP.HTTPRequest internally. This means a single call to 
 function onRefresh()
 {
 	return Engines.KlipFood.process( Prefs.contentsource );
 }
is equivalent to 
 function onRefresh()
 {
 	var request = Engines.HTTP.newRequest( Prefs.contentsource );
 
 	if (request.send() )
 		return Engines.KlipFood.process( request.response.data );
 	else
 		return false;
 }

Creating your own HTTPRequest object, as shown above, lets you reuse an Engines.HTTP.HTTPRequest object for multiple requests, each time modifying its properties and calling send() function again.

Enabling/Disabling Sending of Timestamp

Klipfolio Dashboard automatically optimizes an HTTP request by sending the timestamp of the last successful request (which it remembers) in the request header. This enables the remote web server determine if the requested data has changed since the last request and, if not, responds with an empty body the text HTTP 304 Not Modified messages in the HTTP header. Such request takes very little bandwidth.

The following Klip demonstrates this optimization. 

<klip>
   <identity>
      <title>
         API: 304 Not Modified
      </title>
   </identity>
   <locations>
      <contentsource>
         http://www.serence.com/support/samples/demo/demo-static.xml
      </contentsource>
      <icon>
         http://www.serence.com/support/samples/images/sample_icon.png
      </icon>
      <banner>
         http://www.serence.com/support/samples/images/sample_banner.png
      </banner>
   </locations>
   <style>
      alert {
         type: item;
      }

      sender {
         itemcol: 2;
         noterow: 1;

         label: 'Sender';

         emphasis: strong;
      }


      summary {
         itemcol: 3;
         noterow: 4;

         wrap: false;

         notelabel: false;
      }

      date {
         itemcol: 4;
         noterow: 2;

         label: 'Date';
      }

      category {
         noterow: 3;

         label: 'Category';
      }


      level {
         itemcol: 1;
         noterow: 5;
         notelabel: false;
         
         type: image;
      }

      url {
         type: link;
      }
            
      id {
         key: override;
      }
   </style>
   <klipscript>
   <![CDATA[

function onRefresh() 
{   
    var request = Engines.HTTP.newRequest( Prefs.contentsource );
   
    _t( "Access #1: " );
    doHTTPRequest( request );
    
    // - - This access will return a 304 Not Modified message
    _t( "Access #2: " );
    doHTTPRequest( request );
    
    return true;
} 

function doHTTPRequest( request )
{    
    if( request.send() ) 
    {       
       if( request.response.data ) 
       {
         _t( "Got some data!" );
         _t( request.response.headers );
         
         // Add the data to the Klip
         Engines.KlipFood.process( request.response.data );
       }
    } 
    else 
    {
       _t( "Could not reach: " + request.url );
    }
}

function _t( s ) 
{
   trace( s + "\r\n" );
}

   ]]>
   </klipscript>
</klip>

     	

   



	
 
 The first request will return content, while second request will return empty data with a HTTP 304 Not Modified messages in the 
 HTTP header. Here is the output in Klip's Debug Window.
 
 
 

 Access #1: 
 Got some data!
 HTTP/1.1 200 OK
 Server: Zeus/4.3
 Date: Thu, 31 Jul 2008 20:18:06 GMT
 Last-Modified: Tue, 10 Jun 2008 13:45:50 GMT
 Content-Type: text/xml
 Expires: Fri, 01 Aug 2008 20:18:06 GMT
 Content-Length: 721
 Accept-Ranges: bytes
 Cache-Control: max-age=86400
 
 Access #2: 
 Got some data!
 HTTP/1.1 200 OK
 Server: Zeus/4.3
 Date: Thu, 31 Jul 2008 20:18:07 GMT
 Last-Modified: Tue, 10 Jun 2008 13:45:50 GMT
 Content-Type: text/xml
 Expires: Fri, 01 Aug 2008 20:18:07 GMT
 Content-Length: 721
 Accept-Ranges: bytes
 Cache-Control: max-age=86400
 

 
 You can disable this optimization, thus ensuring you always get a response, by setting the
 sendtimestamp property to false before sending the request. For more information about 
 304 messges and headers, see RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 

 


   

   









   
      

         

            
               Properties Summary
         


   
   
   

   
    Engines.HTTP.HTTPResponse
   acceptgzip
   

             Specifies the HTTP request can accept gzip compress response (default false).		
   

   
   

   
    boolean
   autoredirect
   

             Specifies whether Klipfolio Dashboard should follow HTTP redirects (such as 302 Moved Permanently).		
   

   
   

   
    Engines.HTTP.HTTPResponse
   binary
   

             Specifies that response received from the HTTP request stored in the data parameter should be treated as binary (default false).		
   

   
   

   
    Engines.HTTP.HTTPResponse
   binarypost
   

             Specifies that the POST data should treat double-byte Unicode characters as single-byte characters.		
   

   
   

   
    boolean
   cached
   

             Specifies whether Klipfolio Dashboard should try to return a cached copy of the data (if one exists) and store a copy of the data keyed to the specified request URL.		
   

   
   

   
    String
   cookie
   

             Specifies the cookies to be sent with the request.		
   

   
   

   
    String
   headers
   

             Specifies HTTP headers to be sent with the request.		
   

   
   

   
    integer
   maxsize
   

             Specifies the maximum amount of data Klipfolio Dashboard will download from the server before terminating its connection.		
   

   
   

   
    String
   method
   

             Specifies the HTTP method to be used by the request, typically one of GET (default), HEAD, or 
 POST, but may be an arbitrary method such as PROPFIND for WebDAV.		
   

   
   

   
    String
   password
   

             Specifies a password for basic HTTP authentication.		
   

   
   

   
    String
   postdata
   

             Specifies data to be sent with the request following headers for POST requests.		
   

   
   

   
    String
   referer
   

             Specifies the Referer: header sent with the request.		
   

   
   

   
    Engines.HTTP.HTTPResponse
   response
   

             Returns the Engines.HTTP.HTTPResponse object created after the call to send().		
   

   
   

   
    boolean
   sendtimestamp
   

             Specifies whether Klipfolio Dashboard sends an If-Modified-Since header for this request (default true).		
   

   
   

   
    String
   url
   

             The URL to be processed.		
   

   
   

   
    String
   username
   

             Specifies a username for basic HTTP authentication.		
   

   

   

    
   






 









Function Summary




   

      
	 
	     boolean
	 
      
      
	 
	    
	       post( <String> postdata)
	 
	 

	           
	 Sends the HTTP request as a POST request, using postdata as the post data.
      		
   


   

      
	 
	     boolean
	 
      
      
	 
	    
	       send()
	 
	 

	           
	 Sends the HTTP request.
      		
   














   
   

      

         Properties Detail
      

   


   
   
   
acceptgzip

   
Engines.HTTP.HTTPResponse acceptgzip

   
   

   
   
   
autoredirect

   
boolean autoredirect

   
   

   
   
   
binary

   
Engines.HTTP.HTTPResponse binary

   
   

   
   
   
binarypost

   
Engines.HTTP.HTTPResponse binarypost

   
   

   
   
   
cached

   
boolean cached

   
   

   
   
   
cookie

   
String cookie

   
   

   
   
   
headers

   
String headers

   
   

   
   
   
maxsize

   
integer maxsize

   
   

   
   
   
method

   
String method

   
   

   
   
   
password

   
String password