Creating a CSP Page Class
A CSP page class processes requests and generates HTML, writing that HTML directly to the browser. When you create a CSP-based web application, your primary task is to define the OnPage() callback method of your page class or classes.
Basics
To create a CSP page class, do the following:
-
Create a subclass of %CSP.PageOpens in a new tab.
-
In this subclass, implement the OnPage() callback method. This method has access to the following variables:
-
%request, which contains properties with information about the request. This variable is an instance of %CSP.RequestOpens in a new tab.
-
%session, which contains information about the browser session. This variable is an instance of %CSP.SessionOpens in a new tab.
-
%response, which contains information about the default HTTP response. This variable is an instance of %CSP.ResponseOpens in a new tab.
Your method should examine that information as needed, generate the HTML page as a string, and use the Write command to write that string. InterSystems IRIS® data platform automatically redirects the standard output device ($IO) so that all Write output is sent back to the HTTP client.
%CSP.PageOpens in a new tab provides helpful class methods you can use to escape and unescape strings for use in HTML and JavaScript contexts.
Also see Special HTML Directives for an alternative approach.
-
-
Optionally override parameters of %CSP.PageOpens in a new tab, which enable you to control:
-
Default response headers sent to the client
-
Error pages displayed in specific scenarios
For a list of all available class parameters, refer to the documentation for %CSP.PageOpens in a new tab.
-
-
Optionally override other callback methods to control processing at additional times.
For example:
Class GCSP.Basic Extends %CSP.Page
{
ClassMethod OnPage() As %Status
{
Set html="<!DOCTYPE html>"
_"<html lang=""en"" dir=""ltr"">"
_"<body>"
_"<h1>Basic Page</h1>"
// examine %request object and
// write more output...
Set html=html_"</body>"
_"</html>"
Write html //finally, write the page
Quit $$$OK
}
}
This example concatenates the entire page as a single string and then writes it, which is fine for pages expected to be under the long string limit. The following variation produces the identical HTML:
Class GCSP.Basic Extends %CSP.Page
{
ClassMethod OnPage() As %Status
{
write "<!DOCTYPE html>"
_"<html lang=""en"" dir=""ltr"">"
_"<body>"
_"<h1>Basic Page</h1>"
// examine %request object and
// write some more html...
write "</body>"
_"</html>"
Quit $$$OK
}
}
Note that when there are multiple pages that need to have the same overall appearance, it is better to have separately testable helper methods for constructing the page start, the <head> with the HTML meta data, any JavaScript, links to style sheets, the navigation <div>s, the footer, the page end, and so on.
Controlling the Default Response Headers
Class parameters in your CSP page class determine the default HTTP response headers sent to the client.
To control the type of content returned to the browser, specify the CONTENTTYPE class parameter. For example:
Parameter CONTENTTYPE = "application/vnd.ms-excel";
Similarly, to control the character set used, specify the CHARSET class parameter:
Parameter CHARSET = "UTF-8";
For a list of all available class parameters, refer to the documentation for %CSP.PageOpens in a new tab.
You can also control the HTTP headers of the response by setting properties of the %response object, within the OnPreHTTP() callback, discussed next.
Other Callbacks
When InterSystems IRIS® data platform determines which %CSP.PageOpens in a new tab class should process a request, it calls the Page() method of the class, which in turn calls these callback methods in order:
-
OnPreHTTP()
-
OnPage() discussed above
-
OnPostHTTP()
OnPreHTTP()
You can implement OnPreHTTP() for finer control of the HTTP headers of the response.
Specifically, you can set properties of the %response object, such as the ContentType property, if that needs to be different from the default that you chose:
set %response.ContentType="text/html"
Then InterSystems IRIS uses those values when writing to the client.
The OnPreHTTP() method is also where you can define redirects, if needed. You can create a normal client-side redirect by setting the Redirect property:
set %response.Redirect="https://someotherurl"
Or, if you want to invoke another CSP page, you can instead set the ServerSideRedirect property, which will cause the CSP Server to invoke the Page() method in the specified class.
set %response.Redirect="GCSP.OtherPage.cls"
Note that a server-side redirect does not change the URL seen in the browser.
OnPostHTTP()
The OnPostHTTP() method is provided as a place to perform any operations you wish to perform after processing of the HTTP request is complete.
Best Practice for Links
When you include an HTML <A> anchor link, use the Link() method of %CSP.PageOpens in a new tab to create the URL. This method performs any URL escaping and also encrypts the URL parameters if applicable (depending on the definition of the target page).
This method has the following signature:
classmethod Link(link As %String, ByRef query As %String,
addQ As %Boolean = 0) as %String
Where:
-
link is the base URL
-
query is a multidimensional array containing any URL parameters
-
addQ is a Boolean value specifying whether to include a trailing ? or & (as appropriate) at the end of the returned value. This option enables you to append additional query parameters.
For example:
Set origurl="GCSP.EncryptPage2.cls"
Set urlparms("SAMPLEPARM")="sample value"
Set tURL = ##class(%CSP.Page).Link(origurl,.urlparms)
Set html="<p>Link to page 2: <a href="""_tURL_""">Link</a>"_"</p>"
You can also use the Context property of the %response object to automatically insert values into all links and forms; see the class reference for details.
Tag-Based Development (Legacy)
Legacy applications may also include .csp files, which are used in tag-based development. In the tag-based development model, the developer creates .csp files contained within the directory structure accessed by the web application. The files contain a mix of HTML and specialized tags that provide for communication with the server. The CSP compiler reads the files and generate class definitions from them, and the class definitions generate the actual runtime HTML. For information on tag-based development, consult Tag-based Development with CSPOpens in a new tab in the Caché/Ensemble documentation.