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

- add(subnode)

- addAt(position, subnode)

- clearCache()

- contains(obj)

- count()

- get(id)

- getById(id, proto)

- getChildElement(name)

- getOrderedView(name)

- getResource(resourceName)

- getResources(resourceName)

- href(action)

- invalidate(childId)

- indexOf(obj)

- isPersistent()

- isTransient()

- list()

- persist()

- prefetchChildren(startIndex, length)

- remove()

- removeChild(child)

- renderSkin(skin, params)

- renderSkinAsString(skin, params)

- size()

- update()

- onCodeUpdate()

- onInit()

- onPersist()

- onUnhandledMacro(name)

- onRequest()

- onResponse()

properties

- Date __created__

- Number _id

- Date __lastModified__

- String _name

- HopObject _parent

- String _prototype

- Object cache

see

Packages.helma.scripting.rhino.HopObject

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

HopObject.clearCache

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

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.add

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.cache

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.indexOf

HopObject. count()
Get the number of subnodes attached to this HopObject.
Example:

    res.write(root.count());
    5

returns

| Number of subnodes

see

HopObject.size

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.
Otherwise, if the argument is a string, this function's 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 returns the subnode with the corresponding name.
If an accessname is not defined, 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. This behavior is better achieved with HopObject method getById().
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

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.get

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

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.getResource

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

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.isPersistent

HopObject. list()
Returns an array including all subnodes of a HopObject.
The start and count parameters are optional, if omitted, an array of the entire collection of subnodes is returned, otherwise only the specified range.
This function is most useful if the whole collection of a HopObject's subnodes should be retrieved as array. However, general use should be avoided in favor of the method described below.
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

With increasing amounts of subnodes tied to a HopObject the use of list() becomes seriously inefficient in cases where not all subnodes really need to be read out.
This is due to the creation of a JavaScript array containing the whole bunch of subnodes each time the function is called.
Instead, it is recommended to determine the amount of subnodes using the function count() and looping through the subnode collection using the get() function.

    var amount = root.size();
    for (var i=0; i < amount; i++){
    var myObject = root.get(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

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

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.remove

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
global.renderSkin
global.renderSkinAsString

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.renderSkin
global.renderSkin
global.renderSkinAsString

HopObject. size()
Get the number of subnodes attached to this HopObject.
Example:

    res.write(root.size());
    5

returns

| Number of subnodes

see

HopObject.count

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.
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

res.getBuffer

Tue, 25 Nov 2008 16:50:10 GMT.

### core framework

- global
- app (application)
- req (request)
- res (response)
- session
- path
- root
- HopObject
- User
- File
- FtpClient
- Image
- Mail
- Remote
- Xml
- DatabaseObject
- MimePart
- Skin
- Object

### optional modules

- Array extensions
- Date extensions
- Number extensions
- Object extensions
- String extensions
- HopObject extensions
- global macros
- macro filters
- JSON methods
- helma.Aspects
- helma.Chart
- helma.Color
- helma.Database
- helma.File
- helma.Ftp
- helma.Group
- helma.Html
- helma.Http
- helma.Image
- helma.Mail
- helma.Search
- helma.Skin
- helma.Ssh
- helma.Url
- helma.Zip
- jala.BitTorrent
- jala.Captcha
- jala.Date
- jala.db
- jala.DnsClient
- jala.Form
- jala.History
- jala HopObject extensions
- jala.HtmlDocument
- jala.I18n
- jala.ImageFilter
- jala.IndexManager
- jala.ListRenderer
- jala.Mp3
- jala.PodcastWriter
- jala.RemoteContent
- jala.Rss20Writer
- jala.Utilities
- jala.XmlRpcRequest
- jala.XmlWriter

### java libraries

- browse docjar