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

Object Engines.HTTP.HTTPRequest

Object
   |
   +--Klip
         |
         +--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.Data.process() with a URL, Klipfolio Dashboard automatically creates an Engines.HTTP.HTTPRequest internally. This means a single call to 
 function onRefresh()
 {
 	return Engines.Data.process( Prefs.contentsource );
 }
is equivalent to 
 function onRefresh()
 {
 	var request = Engines.HTTP.newRequest( Prefs.contentsource );

 	if (request.send() )
 		return Engines.Data.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 to 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 in the HTTP header. Such request takes very little bandwidth.

The following Klip demonstrates this optimization. Load it into your Klipfolio Dashboard and see its output in the Debug Window. Then, refresh it again to see that the response header now includes HTTP 304 Not Modified if the data on the server has not changed. 

<klip>
	<identity>
		<title>
			API: 304 Not Modified
		</title>
	</identity>
	<locations>
		<contentsource>
			http://support.klipfolio.com/files/demo/demo.xml
		</contentsource>
		<icon>
			http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
		</icon>
		<banner>
			http://www.klipfolio.com/static/klips/klipfolio/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;
			format: "nolocaltime";
			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() {   
	traceln( "---------------------- Refreshing" );
	var request = Engines.HTTP.newRequest( Prefs.contentsource );
   
	doHTTPRequest( request );
	
	return true;
} 

function doHTTPRequest( request ) {    
	// If the HTTP request is sent successfully
	if ( request.send() ) {       
		// And if a new/changed set of data is returned by the server 
		if ( request.response.data ) {
			traceln( request.response.headers );

			// Add the data to the Klip
			Engines.Data.process( request.response.data );
		}
		// If the data hasn't changed since the last request
		else {
			traceln( request.response.headers );
		}			
	} 
	else  {
		traceln( "---------------------- Could not reach: " + request.url );
	}
}


   ]]>
   </klipscript>
</klip>

     	

   



	

 

 You can disable this optimization, thus ensuring that you always get a response, by setting the
 sendtimestamp property to false before sending the request. For more
 information about
 304 messages 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
   state
   

             A read-only string containing "connected", "connecting" or "disconnected" representing the current state of an asynchronous
 HTTP
 connection.		
   

   
   

   
    integer
   timeout
   

             Specifies the amount of time to wait for the request to return, in seconds.		
   

   
   

   
    String
   url
   

             The URL to be processed.		
   

   
   

   
    String
   username
   

             Specifies a username for basic HTTP authentication.		
   

   

   

    
   






 









Function Summary




   

      
	 
	     function
	 
      
      
	 
	    
	       onData()
	 
	 

	           
	 A function callback handler for receiving data (partial or complete) as a string
 from an
 asynchronous HTTP connection.
      		
   


   

      
	 
	     function
	 
      
      
	 
	    
	       onStateChange()
	 
	 

	           
	 A function callback handler for receiving notifications of changes to the state
 property of an asynchronous HTTP connection as a string
 containing "connected", "connecting" or "disconnected".
      		
   


   

      
	 
	     boolean
	 
      
      
	 
	    
	       post( <String> postdata)
	 
	 

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


   

      
	 
	     boolean
	 
      
      
	 
	    
	       send()
	 
	 

	           
	 Sends the HTTP request.
      		
   


   

      
	 
	     boolean
	 
      
      
	 
	    
	       sendAsync()
	 
	 

	           
	 Sends the HTTP request asynchronously.
      		
   














   
   

      

         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