Default properties and methods of the res object.
This object is automatically instantiated as the res property
of the global object (or global.res) and there is no constructor
to instantiate further instances.
The res object is a host object representing the response for the request that is currently handled by the scripting environment.
For further details also see the JavaDocs for Packages.helma.framework.ResponseBean. Since that class is a JavaBean all of its get- and set-methods are also directly available as properties of this object.
The res object is a host object representing the response for the request that is currently handled by the scripting environment.
For further details also see the JavaDocs for Packages.helma.framework.ResponseBean. Since that class is a JavaBean all of its get- and set-methods are also directly available as properties of this object.
see
Specifies on a per-response base whether to allow client-side caching of the response or not.
The default value is set to true but can be changed globally by passing caching = false to the initial Helma java call.
Please refer to the section about servlet properties for more details.
Example:
The default value is set to true but can be changed globally by passing caching = false to the initial Helma java call.
Please refer to the section about servlet properties for more details.
Example:
res.cache = true
Sets the character encoding of the output.
Sets Helma's character encoding according to the list of supported encodings. By default, Helma uses ISO-8859-1 (western) encoding. It is also possible to set the encoding server or application wide using the charset property in a properties file.
Be careful when setting the charset of a document containing a FORM. The browser returns the user-input encoded in the same way as the document. So if you set for instance the charest to UTF-8 (and don't set it in the app.properties or server.properties) you'll get scrambled input because Helma assumes the input is encoded in the standard encoding (default is ISO-8859-1). So you have to convert the returned strings from UTF8 to ISO-8859-1 (e.g. var string = new java.lang.String(new java.lang.String((req.data.input ? req.data.input : "")).getBytes("ISO-8859-1"), "UTF-8");).
Example:
Sets Helma's character encoding according to the list of supported encodings. By default, Helma uses ISO-8859-1 (western) encoding. It is also possible to set the encoding server or application wide using the charset property in a properties file.
Be careful when setting the charset of a document containing a FORM. The browser returns the user-input encoded in the same way as the document. So if you set for instance the charest to UTF-8 (and don't set it in the app.properties or server.properties) you'll get scrambled input because Helma assumes the input is encoded in the standard encoding (default is ISO-8859-1). So you have to convert the returned strings from UTF8 to ISO-8859-1 (e.g. var string = new java.lang.String(new java.lang.String((req.data.input ? req.data.input : "")).getBytes("ISO-8859-1"), "UTF-8");).
Example:
res.charset = "UTF8"; res.write("Ä Ö Ü ä ö ü ß"); // this is displayed if the brower's encoding is set to "Western" à „ à – à œ à ¤ à ¶ à ¼ à Ÿ
Sets the content type of the HTTP response.
The default value is "text/html".
Example:
The default value is "text/html".
Example:
res.contentType='text/plain'; res.contentType='application/xhtml+xml';
Object providing space for custom output data.
This object can be used to attach any property propertyName onto it to make it available in a skin via the response macro.
Example:
This object can be used to attach any property propertyName onto it to make it available in a skin via the response macro.
Example:
File root/main.skin: <html> <head> <title><% response.title %></title> </head> <body> <% response.body %> </body> </html> File root/main.hac: res.data.title = "Test"; res.data.body = "Hello, World!"; root.renderSkin("main"); <html> <head> <title>Test</title> </head> <body> Hello, World! </body> </html>
Property containing an internal Helma error message.
This property contains a string describing an error if one should have occured. If no error was detected, res.error contains null.
A good place for this function is a custom error page to display errors in a pretty layout.
Example:
This property contains a string describing an error if one should have occured. If no error was detected, res.error contains null.
A good place for this function is a custom error page to display errors in a pretty layout.
Example:
res.write(res.error); Runtime error Syntax error detected near line 1, column 24, after in string starting with: 'function main_action (arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10) {'...
see
Get or set the HTTP ETag for this response.
Get the uncaught exception for the response, if any
since: 1.7
see
The res.handlers object is a container in the response object used to register
macro handlers for the current request/response.
Adding an object to res.handlers will make its macro functions and/or properties available as macros for skins.
By default, res.handlers contains the objects in the request path, registered by their prototype names. For instance, res.handlers.root will always be a reference to the app's root object.
Adding an object to res.handlers will make its macro functions and/or properties available as macros for skins.
By default, res.handlers contains the objects in the request path, registered by their prototype names. For instance, res.handlers.root will always be a reference to the app's root object.
Get the Java stack trace of an uncaught exception, if any
since: 1.7
see
Sets the date the resource was retrieved by the remote client.
By setting this property the remote client is told that the served resource has been modified at the given time. You then can check if the resource has changed given that the client includes this date in future requests for this resource.
Example:
By setting this property the remote client is told that the served resource has been modified at the given time. You then can check if the resource has changed given that the client includes this date in future requests for this resource.
Example:
//in this example this.modificationDate is a property storing //the time of the last changes to the current object res.lastModified = this.modificationDate;
Buffers a string for output.
When this property is set its value can be retrieved either by res.message from within an action or a JavaScript file or by the response macro from within a skin file.
Additionally, it will survive an HTTP redirect which can be necessary to display warnings or error messages to the user. The property's value will be reset to null not later than a redirected response was output.
Note: Please be aware that both res.message and res.data.message corresponds to the response.message macro. However, res.message has higher priority if both values should be set.
Example:
When this property is set its value can be retrieved either by res.message from within an action or a JavaScript file or by the response macro from within a skin file.
Additionally, it will survive an HTTP redirect which can be necessary to display warnings or error messages to the user. The property's value will be reset to null not later than a redirected response was output.
Note: Please be aware that both res.message and res.data.message corresponds to the response.message macro. However, res.message has higher priority if both values should be set.
Example:
File main.skin: <% response.message %> File main.hac: res.message = "Hello, World!"; res.data.message = "Test"; this.renderSkin("main"); Hello, World!
Object providing space for general purpose per request meta information.
This object can be used to attach any property propertyName onto it to make it available within the scope a request.
Example:
This object can be used to attach any property propertyName onto it to make it available within the scope a request.
Example:
Inside an onRequest handler function: res.meta.permissions = this.doSomething(); Inside an action such as delete.hac: if(res.meta.permissions | 7) this.remove();
Sets the realm for a HTTP-authentication challenge
This defines the realm for a HTTP-authentication challenge. The realm is the name of a protected space. A server can have several realms, but resources within one realm should share the same authorisation - a valid authorisation should be valid as well for requesting another resource within the same realm.
Example:
This defines the realm for a HTTP-authentication challenge. The realm is the name of a protected space. A server can have several realms, but resources within one realm should share the same authorisation - a valid authorisation should be valid as well for requesting another resource within the same realm.
Example:
res.status = 401; res.realm = "Helma protected area";
Get the Javascript stack trace of an uncought exception, if any
since: 1.7
see
Provides direct access to the servlet response header, a
Java object of the class Packages.javax.servlet.http.HttpServletResponse
Example:
Example:
res.servletResponse.setHeader( "Content-Disposition", ( this.mimetype.startsWith( "image/" )? "" : "attachment;" ) + "filename=\"" + this.name + "\"" );
see
The res.skinpath can be set to an array that tells Helma where to
look for skinsets for the current request/response.
The elements of the array should be either HopObjects, which will be interpreted as database-resident skinsets, or strings, which will be interpreted as directory paths leading to file based skin sets.
If hobj is a HopObject element in the res.skinpath array, then a skin for prototype proto named sname is expected to reside in a string property in hobj.proto.sname.skin.
If path is a string, then the same skin will be looked up in a file called path/proto/sname.skin.
The elements of the array should be either HopObjects, which will be interpreted as database-resident skinsets, or strings, which will be interpreted as directory paths leading to file based skin sets.
If hobj is a HopObject element in the res.skinpath array, then a skin for prototype proto named sname is expected to reside in a string property in hobj.proto.sname.skin.
If path is a string, then the same skin will be looked up in a file called path/proto/sname.skin.
Read/write property containing the response's HTTP-status code.
This property defines the status code of the HTTP response. Like any HTTP-Server Helma can send the client software additional information describing the response. For a list of all codes and their meaning see RFC 2616. One of the common usages is to deny access and ask for authentication by responding with status code 401. The client software usually responds by asking the user for username and password. The default value is 200 which is the code for "OK".
Example:
This property defines the status code of the HTTP response. Like any HTTP-Server Helma can send the client software additional information describing the response. For a list of all codes and their meaning see RFC 2616. One of the common usages is to deny access and ask for authentication by responding with status code 401. The client software usually responds by asking the user for username and password. The default value is 200 which is the code for "OK".
Example:
res.status = 401; //make sure to set res.realm as well when asking for http authentication res.realm = "Helma protected area";
Methods
Proxy to res.servletResponse.addHeader()
parameters
String | name | as String, the header name |
String | value | as String, the header value |
see
Proxy to res.servletResponse.addDateHeader()
parameters
String | name | as String, the header name |
Date | value | as Date, the header value |
see
Commits the current transaction, writing all changed objects to the database, and starts a new transaction.
Usually, Helma automatically wraps each request into a database transaction. Use res.commit() if you have to modify a huge ammount of HopObjects within one request and want to partition the transaction into several smaller ones.
Example:
Usually, Helma automatically wraps each request into a database transaction. Use res.commit() if you have to modify a huge ammount of HopObjects within one request and want to partition the transaction into several smaller ones.
Example:
for (var i in collection1) collection1.get(i).counter += 1; // commit changes to elements of collection1 to db res.commit(); for (var i in collection2) collection2.get(i).counter -= 1; // changes to elements of collection2 are committed // automatically when the request terminates
see
Append any value to the output of the current page.
All values written with res.debug() will appear as separate items at the bottom of the page. This assumes that the content type of the current request is text/html. Since items are simply appended to the full page, res.debug() will most likely break the well-fomedness of your page, but it is usually displayed properly.
Transforms the passed argument to a string (only if necessary) and appends the result to the response debug buffer.
Example:
All values written with res.debug() will appear as separate items at the bottom of the page. This assumes that the content type of the current request is text/html. Since items are simply appended to the full page, res.debug() will most likely break the well-fomedness of your page, but it is usually displayed properly.
Transforms the passed argument to a string (only if necessary) and appends the result to the response debug buffer.
Example:
var now = new Date(); res.debug("current time: " + now); current time: Tue May 20 18:59:02 CEST 2003
parameters
String | text | as String |
Add an item to this response's dependencies.
If no dependency has changed between requests, an HTTP not-modified response will be generated.
If no dependency has changed between requests, an HTTP not-modified response will be generated.
parameters
String | what | as string, an item this response depends on |
Digest this response's dependencies to conditionally create
a HTTP not-modified response.
Writes a string as smooth HTML to the output buffer.
Encodes a string by replacing linebreaks with <br /> tags and diacritical characters as well as HTML tags with their equivalent HTML entities and immediately outputs it.
Example:
Encodes a string by replacing linebreaks with <br /> tags and diacritical characters as well as HTML tags with their equivalent HTML entities and immediately outputs it.
Example:
res.encode("<b>Bananer växer\n minsann inte på träd.</b>"); <b>Bananer växer <br /> <br> minsann inte på träd.</b>
parameters
String | textToEncode | as String |
see
Writes a string to the output buffer, leaving linebreaks untouched.
Performs the following string manipulations:
Example:
Performs the following string manipulations:
- Unlike encode, leaves linebreaks untouched. This is what you usually want to do for encoding form content (esp. with text input values).
- All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.
- Existing markup tags are being encoded.
Example:
var str = res.encodeForm("<b>Bananer växer\n minsann inte på träd.</b>"); <b>Bananer växer minsann inte på träd.</b>
parameters
String | textToEncode | as String |
see
Writes a string to the output buffer, replacing some characters with their equivalent XML entities.
This function substitutes the characters '<', '>', '&', as well as single and double quotes with their predefined XML 1.0 entities. Additionally, some characters that are illegal in XML documents are silently dropped.
encodeXml() is usually used to encode text for safe inclusion in parsed character data sections of XML documents.
Example:
This function substitutes the characters '<', '>', '&', as well as single and double quotes with their predefined XML 1.0 entities. Additionally, some characters that are illegal in XML documents are silently dropped.
encodeXml() is usually used to encode text for safe inclusion in parsed character data sections of XML documents.
Example:
res.encodeXml("<title>Smørebrød</title>"); <title>Smørebr&oslash;d</title>
parameters
String | textToEncode | as String |
see
Writes a string as smooth HTML to the output buffer.
This function outputs a string after substituting special characters in a string with their equivalent HTML entities but keeping markup tags as is and also tries to avoid
tags where ever possible (e.g. in table structures).
Example:
This function outputs a string after substituting special characters in a string with their equivalent HTML entities but keeping markup tags as is and also tries to avoid
tags where ever possible (e.g. in table structures).
Example:
res.format("<table>\n<tr><td>Bananer växer\n minsann inte på träd.</td></tr>\n</table>"); <table> <tr><td>Bananer växer <br /> minsann inte på träd.</td></tr> </table>
parameters
String | textToFormat | as String |
see
Serves a static file from the application's protectedStatic directory.
Used to serve static files from the application's protectedStatic directory. This "protected" static directory needs to be set by defining an appname.protectedStatic property in the apps.properties file. The contents of that directory are not made directly accessible through the web, only through the use of this res.forward() method.
Used to serve static files from the application's protectedStatic directory. This "protected" static directory needs to be set by defining an appname.protectedStatic property in the apps.properties file. The contents of that directory are not made directly accessible through the web, only through the use of this res.forward() method.
parameters
String | path | as String, relative to this app's protectedStatic directory |
Provides access to the contents of the current repsonse buffer.
Useful for example when parsing/modifying the response after the request has been handled but before the response is returned.
Useful for example when parsing/modifying the response after the request has been handled but before the response is returned.
returns
String |
see
Pops a string buffer from the response object and returns its string value.
This function "pops" a string buffer from the response object. The returned string contains all output written to the response since the last call of res.push().
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:
This function "pops" a string buffer from the response object. The returned string contains all output written to the response since the last call of res.push().
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:
res.push(); res.write("foo"); res.encode('.'); res.write("bar"); var str = res.pop() // str is "foo.bar"
returns
String |
see
Pops the current response buffer without converting it to a string.
This function "pops" the current StringBuffer from the response object and returns it as a Java StringBuffer object.
This function "pops" the current StringBuffer from the response object and returns it as a Java StringBuffer object.
returns
StringBuffer |
see
Pushes a new string buffer on the response object.
This function "pushes" a fresh string buffer on the response object to which all response output will be redirected until res.pop() is called to retrieve the generated string.
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:
This function "pushes" a fresh string buffer on the response object to which all response output will be redirected until res.pop() is called to retrieve the generated string.
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:
res.push(); res.write("foo"); res.encode('.'); res.write("bar"); var str = res.pop(); // str is "foo.bar"
see
Pushes a Java StringBuffer object on the reponse object.
This function "pushes" the provided StringBuffer to the response object. All further writes will be redirected to this buffer.
This function "pushes" the provided StringBuffer to the response object. All further writes will be redirected to this buffer.
parameters
StringBuffer | strBuffer | as StringBuffer Java object, the StringBuffer to be pushed to the reponse object |
see
Sends an HTTP redirect message to the client.
Note: JavaScript code following this command will be ignored.
Example:
Note: JavaScript code following this command will be ignored.
Example:
res.redirect(this.href());
Resets the current output buffer.
Example:
Example:
res.write("Test"); // changing my mind (e.g. an error occured) res.reset(); res.write("Hello, World!"); Hello, World!
Resets the response buffer, clearing all content
previously written to it.
Rollback the current transaction and start a new one.
exceptions
Exception thrown if rollback fails |
see
Sets a cookie to be sent to the client machine.
All arguments after nameString and valueString are optional.
daysNumber specifies the number of days until the cookie expires. If set to 0, the cookie will be deleted immediately. If the argument is not specified or set to a negative value, the cookie will be discarded is at the end of the browser session.
pathString specifies the path on which to set the cookie (defaults to /)
domainString specifies the domain on which to set the cookie (defaults to unset)
Example:
All arguments after nameString and valueString are optional.
daysNumber specifies the number of days until the cookie expires. If set to 0, the cookie will be deleted immediately. If the argument is not specified or set to a negative value, the cookie will be discarded is at the end of the browser session.
pathString specifies the path on which to set the cookie (defaults to /)
domainString specifies the domain on which to set the cookie (defaults to unset)
Example:
res.setCookie("username", "michi"); res.setCookie("password", "strenggeheim", 10, "/mypath", ".mydomain.org");
parameters
String | key | as String |
String | value | as String |
Number | days | as Number |
String | path | as String |
String | domain | as String |
Proxy to res.servletResponse.setHeader()
parameters
String | name | as String, the header name |
String | value | as String, the header value |
see
Proxy to res.servletResponse.setDateHeader()
parameters
String | name | as String, the header name |
Date | value | as Date, the header value |
see
Stops the execution of the request and sends the content of the reponse buffer.
Note that this method is intended for use in the context of an onRequest handler and not for use inside of actions, which would likely lead to bad coding practices.
Example:
Note that this method is intended for use in the context of an onRequest handler and not for use inside of actions, which would likely lead to bad coding practices.
Example:
function onRequest() { if (fooIsCached()) { res.write(fooFromCache()); res.stop(); } }
see
Writes a string to the output buffer.
Transforms the passed argument to a string (only if necessary) and appends the result to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:
Transforms the passed argument to a string (only if necessary) and appends the result to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:
var now = new Date(); res.write("current time: " + now); current time: Thu Feb 15 23:34:29 GMT+01:00 2001
parameters
String | text | as String |
Writes binary data to the output buffer.
This function takes one argument, which must be a Java byte array. Useful when handling binary data retrieved via http file upload.
Example:
This function takes one argument, which must be a Java byte array. Useful when handling binary data retrieved via http file upload.
Example:
var upload = req.data.fileUpload; res.writeBinary(upload.getContent());
parameters
Packages.java.ByteArray | data | as Packages.java.ByteArray |
Writes a string to the output buffer, adding a linebreak.
Transforms the passed argument to a string (only if necessary) and appends the result together with a trailing linebreak to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:
Transforms the passed argument to a string (only if necessary) and appends the result together with a trailing linebreak to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:
var now = new Date(); res.writeln("current time:"); res.writeln(now); current time:
Thu Feb 15 23:34:29 GMT+01:00 2001
parameters
String | text | as String |
Unset a previously set HTTP cookie, causing it to be
discarded by the HTTP client immediately.
parameters
String | key | as String, the name of the cookie to be discarded |