Detailed reference of prototypes, properties and methods available in the
Javascript environment of your Helma web applications.

Default properties and methods of the res object.
ResponseBean res
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.
see
Boolean res. cache
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:
res.cache = true
String res. charset
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:
res.charset = "UTF8";
res.write("Ä Ö Ü ä ö ü ß");
// this is displayed if the brower's encoding is set to "Western"
à „ à – à œ à ¤ à ¶ à ¼ à Ÿ
String res. contentType
Sets the content type of the HTTP response.

The default value is "text/html".

Example:
res.contentType='text/plain';
res.contentType='application/xhtml+xml';
Object res. data
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:
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>
String res. error
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:
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
String res. etag
Get or set the HTTP ETag for this response.
String res. exception
Get the uncaught exception for the response, if any
since: 1.7
see
Object res. handlers
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.
String res. javaStack
Get the Java stack trace of an uncaught exception, if any
since: 1.7
see
Date res. lastModified
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:
//in this example this.modificationDate is a property storing
//the time of the last changes to the current object
res.lastModified = this.modificationDate;
String res. message
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:
File main.skin:
<% response.message %>
 
File main.hac:
res.message = "Hello, World!";
res.data.message = "Test";
this.renderSkin("main");
 
Hello, World!
Object res. meta
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:
Inside an onRequest handler function:
  res.meta.permissions = this.doSomething();
 
Inside an action such as delete.hac:
if(res.meta.permissions | 7)
  this.remove();
String res. realm
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:
res.status = 401;
res.realm = "Helma protected area";
String res. scriptStack
Get the Javascript stack trace of an uncought exception, if any
since: 1.7
see
HttpServletResponse res. servletResponse
Provides direct access to the servlet response header, a Java object of the class Packages.javax.servlet.http.HttpServletResponse

Example:
res.servletResponse.setHeader( "Content-Disposition", 
  ( this.mimetype.startsWith( "image/" )? "" : "attachment;" ) +  
  "filename=\"" + this.name + "\"" );
see
Array res. skinpath
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.
Number res. status
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:
res.status = 401;
//make sure to set res.realm as well when asking for http authentication
res.realm = "Helma protected area";
Methods
res. abort()
Aborts the current transaction by throwing an Error
see
res. addHeader(name, value)
Proxy to res.servletResponse.addHeader()
parameters
String name as String, the header name
String value as String, the header value
see
res. addDateHeader(name, value)
Proxy to res.servletResponse.addDateHeader()
parameters
String name as String, the header name
Date value as Date, the header value
see
res. commit()
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:
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
res. debug(text)
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:
var now = new Date();
res.debug("current time: " + now);
 
current time: Tue May 20 18:59:02 CEST 2003
parameters
String text as String
res. dependsOn(what)
Add an item to this response's dependencies.

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
res. digest()
Digest this response's dependencies to conditionally create a HTTP not-modified response.
res. encode(textToEncode)
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:
res.encode("<b>Bananer växer\n minsann inte på träd.</b>");
&lt;b&gt;Bananer v&auml;xer
&lt;br /&gt; &lt;br&gt; minsann inte p&aring; tr&auml;d.&lt;/b&gt;
parameters
String textToEncode as String
see
res. encodeForm(textToEncode)
Writes a string to the output buffer, leaving linebreaks untouched.

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>");
 
&lt;b&gt;Bananer v&auml;xer
minsann inte p&aring; tr&auml;d.&lt;/b&gt;
parameters
String textToEncode as String
see
res. encodeXml(textToEncode)
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:
res.encodeXml("<title>Smørebr&oslash;d</title>");
&lt;title&gt;Smørebr&amp;oslash;d&lt;/title&gt;
parameters
String textToEncode as String
see
res. format(textToFormat)
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:
res.format("<table>\n<tr><td>Bananer växer\n minsann 
inte på träd.</td></tr>\n</table>");
<table>
<tr><td>Bananer v&auml;xer
<br />
minsann inte p&aring; tr&auml;d.</td></tr>
</table>
parameters
String textToFormat as String
see
res. forward(path)
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.
parameters
String path as String, relative to this app's protectedStatic directory
res. getBuffer()
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.
returns
String
see
res. pop()
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:
res.push();
res.write("foo");
res.encode('.');
res.write("bar");
var str = res.pop()
// str is "foo.bar"
returns
String
see
res. popBuffer()
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.
returns
StringBuffer
see
res. push()
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:
res.push();
res.write("foo");
res.encode('.');
res.write("bar");
var str = res.pop();
// str is "foo.bar"
see
res. pushBuffer(strBuffer)
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.
parameters
StringBuffer strBuffer as StringBuffer Java object, the StringBuffer to be pushed to the reponse object
see
res. redirect()
Sends an HTTP redirect message to the client.

Note: JavaScript code following this command will be ignored.

Example:
res.redirect(this.href());
res. reset()
Resets the current output buffer.

Example:
res.write("Test");
// changing my mind (e.g. an error occured)
res.reset();
res.write("Hello, World!");
 
Hello, World!
res. resetBuffer()
Resets the response buffer, clearing all content previously written to it.
res. rollback()
Rollback the current transaction and start a new one.
exceptions
Exception thrown if rollback fails
see
res. setCookie(key, value, days, path, domain)
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:
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
res. setHeader(name, value)
Proxy to res.servletResponse.setHeader()
parameters
String name as String, the header name
String value as String, the header value
see
res. setDateHeader(name, value)
Proxy to res.servletResponse.setDateHeader()
parameters
String name as String, the header name
Date value as Date, the header value
see
res. stop()
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:
function onRequest() {
  if (fooIsCached()) {
    res.write(fooFromCache());
    res.stop();
  }
}
see
res. write(text)
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:
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
res. writeBinary(data)
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:
var upload = req.data.fileUpload;
res.writeBinary(upload.getContent());
parameters
Packages.java.ByteArray data as Packages.java.ByteArray
res. writeln(text)
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:
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
res. unsetCookie(key)
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
Fri, 05 Feb 2010 17:40:04 GMT.

core framework

optional modules

java libraries

properties files