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

Default properties and methods of the HopObject prototype.
HopObject()
Constructor for HopObject objects, providing the building blocks of the Helma framework.

Extends the standard JavaScript object with Helma-specific properties and functions. The HopObject is the basic building block of a Helma application. The website root object as well as custom types defined by the application inherit from the HopObject prototype.

HopObjects can be given special Helma specific properties, such as "collections" that can be configured to map to relational databases, and will make such data available when rendering "skins".

HopObjects can be in transient state or are persistently mapped on a database. HopObjects that are directly or indirectly attached to the application's root object are automatically persisted using the built-in XML database, if they are not otherwise mapped to a relational database. see JavaDocs for helma.scripting.rhino.HopObject
methods
  • addAt(position, subnode)
  • list(startIndex, length)
properties
see
Date HopObject. __created__
The creation date of the HopObject.
Number HopObject. _id
The unique id of the HopObject. This property is read-only
Date HopObject. __lastModified__
The date when the HopObject was last modified.
String HopObject. _name
The accessname of the HopObject.
HopObject HopObject. _parent
The parent collection containing this HopObject.
String HopObject. _prototype
The name of the prototype from which this HopObject is inheriting.
Object HopObject. cache
Cache object providing space for arbitrary run-time data.

Each HopObject contains a cache object to store temporary properties (strings, numbers, objects etc.), a transient HopObject, which can be used for caching purposes.

These properties can be accessed in any thread until the application is restarted or the HopObject is invalidated, either manually using the invalidate method, or when the clearCache method is being called, or whenever Helma is updating the HopObject's data from a remote database.

There is no way to make the cache object persistent.

Example:
var obj = root.get(0);
obj.cache.message = "This is a temporary message."
see
Methods
HopObject. add(subnode)
Attaches a HopObject as an additional subnode.

Adds a HopObject as new subnode to another HopObject. The new subnode is added after the last subnode already contained in the parent HopObject.

If the subnode is already attached, it is moved to the last index position.
parameters
HopObject subnode as HopObject to add to this node.
returns
Boolean true if the addition or move was successful.
see
HopObject. addAt(position, subnode)
Attaches an additional subnode at the given index.

Adds a HopObject to a collection at a certain position, and shifts the index of all succeeding objects in that collection by one. Index positions start with 0. Any out of range moves will move the subnode to the last index position.

Just makes sense for HopObjects, that are not mapped on a relational DB, since the sort order of the collection would otherwise be defined by type.properties, resp. by the database itself. Returns true in case of success. If the subnode is already attached, it will be moved to the specified index position.
parameters
Number position as Number, the index position where the subnode is to be inserted.
HopObject subnode as HopObject to add to this node.
returns
Boolean true if the addition or move was successful.
see
HopObject. clearCache()
Clears this HopObject's cache property.

Removes all information stored in the cache object. Doing this by just calling 'obj.cache = null' is not possible, since the property itself can not be set.
see
HopObject. contains(obj)   deprecated use indexOf instead
Determines if a HopObject contains a certain subnode.
parameters
HopObject obj as HopObject, the node to look for
returns
Number of the index position or -1
see
HopObject. count()
Get the number of subnodes attached to this HopObject.

Example:
res.write(root.count());
5
returns
Number of subnodes
see
HopObject. get(id)
Retrieves a persisted HopObject that is a subnode or a mapped property of this HopObject.

If the argument is a number, this method returns the subnode of this HopObject at the corresponding index position.

If the argument is a string and matches a property name mapped in this prototype's type.properties file to a mountpoint, object, or collection, this function returns the corresponding HopObject.

If the string argument produces no such match, the behavior depends on whether this HopObject's _children have an accessname defined in the prototype's type.properties.

If an accessname is defined, this function first attempts to return the subnode with the corresponding name. Otherwise, or if that attempt fails, a string argument will result in a null return unless the string argument is numeric, in which case this function will return the child with an _id matching the numeric value of the argument. However, retrieving a HopObject based on its _id value is better achieved using the getById() HopObject method.

Example:
root.get(0);
HopObject author
root.get(1);
HopObject story
 
root.get("date");
Wed Oct 18 02:01:41 GMT+01:00 1971
root.get("title");
The Nudist On The Late Shift
parameters
String id as String or Number
returns
HopObject the subnode with the specified id or name
see
HopObject. getById(id, proto)
Retrieves the specified HopObject.

If called on a HopObject instance, this getById() retrieves a child object by ID. If called on a HopObject constructor, it retrieves the persisted HopObject of that prototype and with the specified ID.

Fetches a HopObject of a certain prototype through its ID and its prototype name. The prototype name can either be passed as a second argument, or alternatively the function can also be called on the prototype itself with a single argument (e.g. Story.getById(123)).

In case of multiple prototypes being mapped on the same table (which is for instance the case with inherited prototypes) Helma will not check whether the prototype of the fetched object actually matches the specified prototype.

Note, that this refers to the static method 'getById', not to be mixed up with the method getById called on a specific HopObject.

Example:
//get the child with id 17
var child = root.getById(17);
writeln(child._id);
17
 
//get the child at index 17 of the HopObject's children-collection
child = root.get(17);
writeln(child._id);
42
 
//get the child with the name "17" (_children.accessname = name) of the HopObject
child = root.get("17");
writeln(child._id);
69
writeln(child.name);
17
 
//get the persistent HopObject with prototype "Page" and id 127
var page = HopObject.getById(127, "Page");
writeln(page._id);
127
 
//get the persistent HopObject with prototype "Page" and id 127
var page = Page.getById(127);
writeln(page._id);
127
parameters
Number id as Number
String proto as String, the name of the prototype
returns
HopObject that was retrieved
see
HopObject. getCollection(props)
Returns a collection of HopObjects as defined by a provided properties object.

The getCollection function is a static method of HopObject constructors, taking a single JS object argument, which provides the collection properties as you would otherwise define them in the _children section of a type.properties file.

Examples:
var c = Page.getCollection({
  order: "name",
  filter: "id > 10",
};
You can also specify the type of contained objects using the "collection" property, so the following collection is equivalent to the one defined above:
var c = HopObject.getCollection({
  collection: "Page",
  order: "name",
  filter: "id > 10",
};
Note that for "nested" properties such as group.order or local.1 you have to use quoted "flat" properties, not nested objects:
var c = Page.getCollection({
  group: "author",
  "group.order": "author",
  "group.prototype": "AuthorGroup"
});
Additionally, the collection properties "limit" and "offset" provide support for easy pagination. In order to fetch pages 11-20, you would do something like this:
var q = Page.getCollection({
  limit: 10,
  offset: 10
});
Note that "limit" is just an alias for "maxSize" introduced to be more consistent with the underlying SQL syntax.

This feature is currently implemented and known to work on MySQL, Postgresql, and Oracle.
parameters
Object props as Object, properties defining the desired collection
returns
Array the collection of HopObjects as defined by the provided properties
HopObject. getChildElement(name)
Optional handler to override the default URL path resolution.

If defined, the getChildElement() method is called on an object contained in the request path in order to determine the URL path resolution from that object to its (potential) child objects.

The string parameter passed to this method is the name of the next element in the URL path being resolved. The object being returned by this method is then used to continue resolving the URL path.

Example:
function getChildElement(name) {
  if (name == 'transient') {
    return new HopObject();
  }
  else {
    return this.get(name);
  }
}
parameters
String name as String, the name of the child element in the requested URL path
returns
HopObject the child object to be used for further path resolution
HopObject. getOrderedView(name)
Returns a collection including all subnodes of a HopObject ordered according to the properties listed in the string passed as argument.

While the sort pattern, passed as string argument, uses an SQL-like notation for the sorting, it contains property names, not database column names.

The method returns a collection object that is ordered according to the specified sort order. The returned collections are cached and bound to the original collections, i.e. they reflect changes to the original collection. Both initial ordering and re-ordering are done on the Helma side, meaning that no additional db traffic is generated by multiple ordered views.

Example:
var orderedByDate = hobj.getOrderedView("createtime desc, name");
var collection = orderedByDate.list();
for (var i in collection) {
  doSomething(collection[i]);
}
// other syntax examples:
var orderedByName = hobj.getOrderedView("name");
var collectionByName = hobj.collection.getOrderedView("name");
parameters
String name as String, the property names to sort by
returns
HopObject HopObject containing the sorted subnodes
HopObject. getResource(resourceName)
Returns a helma.framework.repository.Resource object defined for the prototype.

Returns a resource referenced by its name for the current HopObject's prototype - getResource() walks up the inheritance chain and through all defined repositories to find the resource and returns null if unsucessful.

Example:
root.getResource("main.skin");
/usr/local/helma-apps/myApp/repository1/HopObject/main.skin
root.getResource("type.properties");
/usr/local/helma-apps/myApp/repository3/Root/type.properties
root.getResource("Functions.js");
/usr/local/helma-apps/myApp/repository17/Root/Functions.js
parameters
String resourceName as String, the name of the requested resource
returns
helma.framework.repository.Resource
see
HopObject. getResources(resourceName)
Returns an Array of helma.framework.repository.Resource objects defined for the prototype.

Returns an array of resources by the specified name for the current HopObject's prototype - getResources() walks up the inheritance chain and through all defined repositories to collect all the resources by that name and returns null if unsucessful.
parameters
String resourceName as String, the name of the requested resource
returns
Array of helma.framework.repository.Resource objects
see
HopObject. href(action)
Returns the absoulte URL path of a HopObject relative to the application's root.

This function is useful when referring to a HopObject in a markup tag (e.g. with a href attribute in an HTML <a>-tag). An optional string argument is appended to the return value.

Example:
var obj = root.get(0);
 
res.write('<a href="' + obj.href() + '">');
<a href="/main/">
 
res.write('<a href="' + obj.href('edit') + '">');
<a href="/main/edit">
parameters
String action as String, optional part to be attached to the URL of this HopObject
returns
String of the URL path for this HopObject
HopObject. invalidate(childId)
Marks a HopObject as invalid so that it is fetched again from the database.

Helma will overwrite the HopObject's node cache with the database contents the next time the HopObject is accessed.

In other words, use this function to kick out an HopObject of Helma's node cache and force a database retrieval of the HopObject data.

Example:
var obj = this.get(0);
obj.invalidate();
parameters
childId
HopObject. indexOf(obj)
Determines if a HopObject contains a certain subnode.

Returns the index position of a Subnode contained by a HopObject (as usual for JavaScript, 0 refers to the first position).

The index position is a relative value inside a HopObject (not to be confused with a Hop ID which is unique for each HopObject).

If there is no appropriate subnode inside the HopObject the returned value equals -1.

Example:
var obj = root.get("myObject");
res.write(root.indexOf(obj));
23
 
obj = root.get("blobject");
res.write(root.indexOf(obj));
-1
parameters
HopObject obj as HopObject, the node to look for
returns
Number of the index position or -1
HopObject. isPersistent()
Returns true if the HopObject is in persistent state, meaning that it is stored in the database, and false if it is transient. Persistent state is also assumed if the object is currently in the process of being inserted into or deleted from the database.
returns
true if the HopObject is in persistent state
see
HopObject. isTransient()
Returns true if the HopObject is in transient state, meaning that it is not stored in the database. This method returns false if the object is stored in the database, or is in the process of being inserted into or deleted from the database.
returns
true if the the HopObject is in transient state
see
HopObject. list(startIndex, length)
Returns an array including all subnodes of a HopObject.

The startIndex and length parameters are optional, if omitted, an array of the entire collection of subnodes is returned, otherwise only the specified range.

Example:
var objectList = root.list();
for (var i=0; i < objectList.length; i++){
  var myObject = objectList[i];
  res.writeln(myObject.created);
}
Wed Oct 18 02:01:41 GMT+01:00 1971
Fri Nov 03 13:25:15 GMT+01:00 2000
Mon May 29 07:43:09 GMT+01:00 1999
parameters
Number startIndex as Number
Number length as Number
returns
Array of HopObjects
HopObject. persist()
Stores a transient HopObject and all HopObjects reachable from it to database.

The function returns the id (primary key) of the newly stored HopObject as string, or null if the HopObject couldn't be stored for some reason.

Example:
var hobj = new HopObject();
hobj.foo = new HopObject();
res.debug(hobj.persist());
2
res.debug(hobj.foo._id)
3
HopObject. prefetchChildren(startIndex, length)
Manually retrieving a particular set of subnodes.

This function provides some control of how many subnodes Helma should retrieve from the database and hold prepared in the node cache for further processing.

This means that for large collections Helma does not need to retrieve neither the subset of subnodes via one SQL statement for each subnode nor the whole collection at once via one statement.

Moreover, only subnodes are retrieved that are not in the node cache already which leads to a maximum of caching efficiency and loading performance.

Example:
res.writeln(root.length);
53874
root.prefetchChildren(0, 3);
for (var i=0; i<3; i++)
  res.writeln(i + ": " + root.get(i));
HopObject 1
HopObject 5
HopObject 4
parameters
Number startIndex as Number
Number length as Number
HopObject. remove()
Deletes a HopObject from the database.

The remove() function deletes a persistent HopObject from the database.

Note that additionally you may want to call the removeChild() function on any object holding the deleted object in its child collection in order to notify it that the child object has been removed.

Example:
res.write(parent.size());
24
var child = parent.get(5);
child.remove();
parent.removeChild(child);
res.write(parent.size());
23
see
HopObject. removeChild(child)
Notifies a parent object that a child object has been removed.

The removeChild() function lets a parent object know that a child object has been removed. Note that calling removeChild() will not actually delete the child object. Directly call remove() on the child object in order to delete it from the database.

Example:
res.write(parent.size());
24
var child = parent.get(5);
child.remove();
parent.removeChild(child);
res.write(parent.size());
23
parameters
HopObject child as HopObject
see
HopObject. renderSkin(skin, params)
Renders a skin of a HopObject and writes the result to the output buffer.

Either renders the provided SkinObject or a skin in the HopObject's prototype chain by the specified name.

A skin can contain markup (e.g. HTML or XML) and macros. Macros are references to Helma functions wrapped in special tags (<% and %>). For more information about skin and macro techniques please refer to the section about About Skins.

Optionally, a JavaScript object can be assigned to the function call as second argument. This object's properties later can be accessed from the skin via macro calls of the kind <% param.propertyName %>.

If a param property is not set but referred to in the skin file, it will be replaced with an empty string. Please note that this behaviour is different from generic macro calls.

Example:
Contents of the file root/example.skin:
<html>
<head>
  <title>Hello, <% param.title %>!</title>
</head>
<body bgcolor="<% param.bgcolor %>">
I greet you <% param.amount %> times.
</body>
</html>
Rendering the skin:
var param = new Object();
param.bgcolor = "#ffcc00";
param.title = "World";
param.amount = "12345";
root.renderSkin("example", param);
 
<html>
<head>
<title>Hello, World!</title>
</head>
<body bgcolor="#ffcc00">
I greet you 12345 times.
</body>
parameters
String skin as SkinObject or the name of the skin as String
Object params optional, properties to be passed to the skin
see
HopObject. renderSkinAsString(skin, params)
Renders a skin of a HopObject and returns the result as string.

Either renders the provided SkinObject or a skin in the HopObject's prototype chain by the specified name.

Similar to renderSkin(), this function returns the result of the rendered skin as string instead of immediately writing it to the response object.

Example:
var str = root.renderSkinAsString("example", param);
res.write(str);
 
which is equivalent to
 
root.renderSkin("example", param);
parameters
String skin as SkinObject or the name of the skin as String
Object params as Object, optional properties to be passed to the skin
returns
String containing the result of the rendered skin
see
HopObject. size()
Get the number of subnodes attached to this HopObject.

Example:
res.write(root.size());
5
returns
Number of subnodes
see
HopObject. update()
Refetches updateable Subnode-Collections from the database.

The following conditions must be met to make a subnodecollection updateable:
1) the collection must be specified with collection.updateable=true
2) the id's of this collection must be in ascending order, meaning, that new records do have a higher id than the last record loaded by this collection.
returns
Number of updated nodes
HopObject. onCodeUpdate()
If defined, the onCodeUpdate() function is called whenever the code is recompiled.   This is most useful when code from repositories is dynamically modified by the application during runtime.
HopObject. onInit()
If a HopObject prototype defines a function named onInit(), it will be called on each HopObject that is fetched from embedded or relational database.

Note that it is not called for HopObjects created using a constructor.
HopObject. onPersist()
If a HopObject prototype defines a function named onPersist(), it will be called on each HopObject immediately before it is stored to embedded or relational database.
HopObject. onUnhandledMacro(name)
If a HopObject prototype defines a function named onUnhandledMacro(), it will be called when a macro is rendered on the HopObject that can't be mapped to a macro function or property of the HopObject.
parameters
String name as String, the name of the unhandled macro
HopObject. onRequest()
If defined, the onRequest() function is called on the object specified by the request path just before the action is invoked.

This is useful for performing some code before each and every action in every prototype (when defining the function for the hopobject prototype) or for each action in one prototype. Often, it is used for checking access permissions.
HopObject. onResponse()
If defined, the onResponse() method is called after each page request is handled but before the response is returned.

This method is NOT called when a response is forwarded or redirected using res.forward or res.redirect respectively.

You can access the current repsonse buffer using the method res.getBuffer.
see
Fri, 05 Feb 2010 17:40:03 GMT.

core framework

optional modules

java libraries

properties files