Providing all HTTP output to your HTTP application. This class abstracts the output generation for the various messaging mechanisms (File, COM, ASP) and provides full control over all aspects of HTTP generation.

The Response object is very flexible in that it is designed to handle multiple different output sources via special subclasses that implement only a few methods to handle the physical output generation logistics. Web Connection implements the following:

wwResponse
     wwResponseFile
     wwResponseString
     wwASPResponse

The lower classes implement only a select few low level methods (Write, FastSend etc.), while the core functionality is implemented at the wwResponse level. The Web Connection framework determines which of these subclasses of the wwResponse object to implement based on the request mode of the current request.

Response Lifetime

The Response object is created whenever a wwProcess object is created, which occurs on every hit. Web Connection calls into your custom process class and passes in the Request object as a startup parameter. The request object provides the context required to determine which mechanism (File, String, ASP) is in use and based on that wwProcess creates an instance of the wwResponseXXXX object.

This newly created object becomes your main output mechanism and is passed to your code as a surrogate object of the wwProcess class as wwProcess::oResponse, or simply as a PRIVATE variable called Response (if you use the default processing of the Process method).

Functionality

The Response object is very powerful in the features it provides your application with. At the lowest level it provides the Write() method which is used for all output travelling back to the Web server. Write is the low level that all other methods in the wwResponse object call to get output sent to the server. These other methods simply create more complex HTTP output and eventually call Write() to submit the output into the HTTP output stream.

Write and its slightly more efficient FastSend companion method are the low level functions, but wwResponse also provides a number of high level features:

• ExpandTemplate and ExpandScript can evaluate scripted HTML pages containing Visual FoxPro code and expressions.
  
• ShowCursor can render a VFP cursor/table as an HTML table with a single line of code
  
• Various FormXXXX methods can generate HTML input fields with a couple of parameter values.
  
• Redirect allows you to send an HTTP request to another page.
  
• Authenticate lets you bring up the browser's login dialog.
  
• ContentTypeHeader lets you configure and manage the HTTP header directly.
  
• StandardPage lets you generate a self-contained HTML page with one line of code.
  

HTTP Headers

Every response should have an HTTP header attached to it. By default the Response object creates a standard HTML HTTP header using a content type of text/html which is generated through Response.ContentTypeHeader(), which is implicitly called from many methods such as HTMLHeader, HTMLHeaderEx, ExpandTemplate and ExpandScript. To create headers manually use code like the following:

lcXML = <somecode that generates XML)
Response.ContentTypeHeader("text/xml")
Response.Write( lcXML)

Headers are used for custom HTTP behaviors such as content expiration, content description, cookie, security and much more. Custom headers require that you use the wwHTTPHeader object to create the header. You can then either output this header directly or pass it to one of the highlevel methods as a parameter. This example manually creates output:

oHeader = CREATE('wwHTTPHeader")
oHeader.DefaultHeader()
oHeader.AddCookie("Name","Rick")
oHeader.AddForceReload() && ExpireContent immediately

Response.Write( oHeader.GetOutput() )  && Write the header into the Response stream
Response.Write( ... content here... )

If you use one of the high level methods you'd pass the oHeader object as a parameter:

Response.HTMLHeader("Hello World","Hello World",,oHeader)

SELECT * FROM TT_Cust into cursor TQuery
Response.ShowCursor()

For more info see the wwHTTPheader documentation.

The llNoOutput parameter

The Write method is implemented like this:

wwResponse::Write(lcText,llNoOutput)

The first parameter is the text to send. The second parameter is very important, but optional and allows you to specify whether the text is sent into the HTTP output stream or returned to you as a string! Most other wwResponse object methods also include this same parameter, which allows most methods to be used as string generators rather than outputting to the HTTP stream. This also allows sophisticated nesting of method calls which would otherwise not be possible - a compound method would collect multiple HTML strings into a single string before actually sending the output to the HTTP stream.

You'll see the llNoOutput parameter in most of the wwResponse methods and the behavior is the same for all of them: If you pass it in as .T. the result is returned to you as a string and the input is not actually sent to the HTTP output source.

SubClassing

You'll undoubtably will want to subclass the wwResponse class. Note that you can also subclass the lower level methods, but it's not recommended that you do this since those are considered system classes.

When you subclass wwResponse with your own class you need to make some additional configuration settings to make sure the wwResponseFile/String/ASP classes - which are the ultimately implemented classes that the framework uses - know to use your new subclass. To do this you have to make a change in WCONNECT.H. All the Web Connection classes are created using DEFINE's that identify each class. For the wwResponse class the line is:

#DEFINE WWC_RESPONSE			wwResponse

and you need to replace the wwResponse value with the name of your subclass.

#DEFINE WWC_RESPONSE			wwCustomResponse

Once you do this, make sure you recompile your project or all PRG/VCX files. Once you do the wwResponseFile/String/ASP classes will now use your subclass.

Class Members

Member		Description
	authenticate	This method is used to perform a request for Web server Basic Authentication to occur. When this method is called the browser login dialog box is popped up for the user to type in a username and password. The password is then validated by the Web server typically against the NT (or Windows) user database. The exact validation varies by Web server - IIS uses the NT User database on the server. o.authenticate(lcRealm, lcErrorMsg, llNoOutput)
	Clear	Clears all current output from the HTTP output stream. The object remains valid, but output has to start over. o.Clear()
	contenttypeheader	Adds a Content Type header to a request. Use this method to create a default header or one of the common defaults. For more complex header use the wwHTTPHeader object instead. o.ContenttypeHeader([loHTTPHeader | lcContentType], llNoOutput)
	DownloadFile	Downloads a file to the client resulting in a File Download dialog rather than displaying the content inside of the browser. o.DownloadFile(lcFilename,lcContentType,lcFileDisplayName)
	ExpandScript	The ExpandScript method method is used to expand script pages that contain FoxPro expressions and Code blocks using Active Server like syntax. The method generates a fully self contained HTML page/HTTP output which includes an HTTP header. o.ExpandScript(tcPageName, tnMode, tvContentType, tlTemplateStr, llNoOutput)
	expandtemplate	The ExpandTemplate method is used to expand template pages that contain FoxPro expressions using Active Server like syntax. The method generates a fully self contained HTML page/HTTP output which includes an HTTP header. o.ExpandTemplate(lcPageName, lcContentType, llTemplateString, llNoOutput)
	FastWrite	This method is very similar to the Write method, but is more efficient as it doesn't perform any error checking on the string and doesn't handle the lNoOutput parameter. o.FastWrite(lcText,llNotUsed)
	formbutton	Creates a button HTML form element. o.formbutton(lcName, lcCaption, lcType, lnWidth, lcCustomTags, llNoOutput)
	formcheckbox	Creates an HTML Form Checkbox. o.formcheckbox(lcName, llValue, lcText, lcCustomTags, llNoOutput)
	FormHeader	Creates a <FORM...> tag. Note you're responsible for creating the closing tag at the end of the form. o.FormHeader(lcAction, lcMethod, lcTarget, lcExtraTags, llNoOutput)
	formhidden	Creates a hidden HTML form field. o.formhidden(lcName, lcValue, llNoOutput)
	formradio	Create a Radio Button HTML Form Field. o.formradio(lcName, lcValue, lcText, llSelected, lcCustomTags, llNoOutput)
	formtextarea	Creates an HTML Form TextArea. o.formtextarea(lcName, lcValue, lnHeight, lnWidth,lcCustomTags, llNoOutput)
	formtextbox	Creates an HTML TextBox element. o.formtextbox(lcName, lcValue, lnWidth, lnMaxWidth, lcCustomTags, llNoOutput)
	GetOutput	This method retrieves the currently accumulated HTTP stream output as a string and clears the output stream with a call to the Clear() method. o.GetOutput(llNoClear)
	HRef	This method creates a hyperlink string. o.href(lcLink,lcText,llNoOutput)
	htmlfooter	Creates a footer for a page. Creates </BODY></HTML> tags preceeded by option HTML passed as parm. Optionally pass text to display just prior to tags o.htmlfooter(tcText,tlNoOutPut)
	HTMLHeader	This method provides a high level HTML header generation routine. By default it creates the following: o.HTMLHeader(tcHeader,tcTitle,tcBackground,tcContentType,tlNoOutput)
	HTMLHeaderEx	This method allows you to create custom HTMLHeader and HTTPHeader objects and pass it to this method for output creation. o.HTMLHeaderEx(lvHTMLHeader, lvHTTPHeader)
	IEChart	This method allows embedding of the IE Chart ActiveX Control into your pages driven by data from the currently active cursor when the method is called. The data in the cursor to graph must contain at least two fields in the following format: o.iechart(cChartType,vWidth,cHeight,lNoOutput)
	nooutput	Turns off all output until the wwResponse object is destroyed. o.NoOutput()
	Redirect	HTTP Redirection allows you redirect the current request to another URL. A common scenario is for login operations where the user is trying to access functionality before he's logged in. When the request comes in you can redirect the user to the Login page first. o.redirect(lcUrl,llNoOutput)
	ShowCursor	This method allows easy display of an entire table, simply by having a table or cursor selected and calling this method. You can optionally pass an array of headers as well as a title and the option to automatically sum all numeric fields. oHTML.ShowCursor(@aHeaders, cTitle, lSumNumbers, lNoOutput,cTableTags)
	standardpage	Creates a standalone HTML page. The page is a fully self contained page that looks like this by default: o.StandardPage(cHeader, lcBody, lvHeader,lnRefresh,lcRefreshUrl,llNoOutput)
	TransmitFile	This method allows you send large files to the client without having to use Response.Write() to load these files into a string in Visual FoxPro. o.TransmitFile(lcFilename,lvHeader)
	Write	The Write and FastSend methods are used for all output that is sent to the HTTP output stream. They are the low level methods through which all output from the wwResponse object flows. All other methods of this object call into Write or FastSend to send their output into the HTTP stream. This centralized access makes this object flexible and able to serve different output mechanisms such as File o.Write(lcText,llNoOutput)
	WriteLn	Writes output to the HTTP output stream with trailing carriage returns. This is identical to: o.WriteLn(lcText,llNoOutput)
	writememo	Writes memo fields to output. Formats carriage returns to <p> and <br> as appropriate. o.writememo(lcText, llNoOutput)
	ContentType	Sets the content type of the request for example: text/plain or text/xml. If this value is not set the default content type for a request is always text/html.
	cStyleSheet	This property is used to force the HTMLHeader method to use the specified Cascading Style Sheet. Property asks for a URL that points at the CSS file.

Requirements

Assembly: wwResponse.prg, wwFileResponse.prg, wwStringResponse.prg