HopObject

Object
   |
   +--HopObject

Defined in HopObject.js

See:

- Packages.helma.scripting.rhino.HopObject

Constructor Detail

HopObject

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

See:
- Packages.helma.scripting.rhino.HopObject

_id

Number _id

The unique id of the HopObject. This property is read-only

_parent

HopObject _parent

The parent collection containing this HopObject.

add

Boolean add(<HopObject> 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.

Parameters:
subnode - as HopObject to add to this node.

Returns:
Boolean true if the addition was successful.

See:
- addAt()

addAt

Boolean addAt(<Number> position,<HopObject> 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.

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.

Parameters:
position - as Number, the index position where the subnode is to be inserted.
subnode - as HopObject to add to this node.

Returns:
Boolean true if the addition was successful.

See:
- add()

cache

Object 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:
- clearCache()

clearCache

void 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:
- cache()

contains

Number contains(<HopObject> 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.contains(obj));
 23
  
 obj = root.get("blobject");
 res.write(root.contains(obj));
 -1

Parameters:
obj - as HopObject, the node to look for

Returns:
Number of the index position or -1

count

Number count()

Get the number of subnodes attached to this HopObject.

Example:

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

Returns:
Number of subnodes

See:
- size()

get

HopObject get(<String> id)

Retrieves a property or a subnode of a HopObject.

Either returns the specifed property of this HopObject or fetches the specified HopObject from its persisted subnodes.

For HopObjects that are mapped to a relational database, the id will be matched against the accessname property as defined in the prototype's type.properties.

This method just works for persistent HopObjects.

The type of the result depends on the type of the submitted argument:

A number will retrieve the subnode of the HopObject at the corresponding index position.

A string will retrieve the corresponding property of the HopObject.

A number as string retrieves the subnode with the corresponding Hop ID.

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
  
 root.get("1");
 HopObject author

Parameters:
id - as String or Number

Returns:
HopObject or the retrieved property

getById

HopObject getById(<Number> id,<String> 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:
id - as Number
proto - as String, the name of the prototype

Returns:
HopObject that was retrieved

getChildElement

HopObject getChildElement(<String> 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:
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

getOrderedView

Array getOrderedView(<String> 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");
 for (var i in orderedByDate) {
   doSomething();
 }
 // other syntax examples:
 var orderedByName = hobj.getOrderedView("name");
 var collectionByName = hobj.collection.getOrderedView("name");

Parameters:
name - as String, the property names to sort by

Returns:
Array of the sorted subnodes

getResource

helma.framework.repository.Resource getResource(<String> 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:
resourceName - as String, the name of the requested resource

Returns:
helma.framework.repository.Resource

See:
- getResources()

getResources

Array getResources(<String> 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:
resourceName - as String, the name of the requested resource

Returns:
Array of helma.framework.repository.Resource objects

See:
- getResource()

href

String href(<String> 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:
action - as String, optional part to be attached to the URL of this HopObject

Returns:
String of the URL path for this HopObject

href_macro

void href_macro(param)

macro returns the url for any hopobject

id_macro

void id_macro(param)

macro returns the id of a HopObject

invalidate

void 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();

list

Array 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

loop_macro

void loop_macro(param)

generic macro that loops over the childobjects and renders a specified skin for each of them

Parameters:
Object - providing the following properties: skin: the skin to render for each item (required) collection: the collection containing the items limit: max. number of items per page (req.data.page determines the page number) sort: property name to use for sorting order: sort order (either "asc" or "desc")

onInit

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

onPersist

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

onRequest

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

onUnhandledMacro

void onUnhandledMacro()

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.

persist

void 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

prefetchChildren

void prefetchChildren(<Number> startIndex, <Number> 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:
startIndex - as Number
length - as Number

remove

void 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:
- removeChild()

removeChild

void removeChild(<HopObject> 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:
child - as HopObject

See:
- remove()

renderSkin

void renderSkin(<String> skin, <Object> params)

Renders a skin of a HopObject and writes the result to the output buffer.

The name of the skin is defined by the string parameter.

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:
skin - as String, the name of the skin to be rendered
params - as Object, optional properties to be passed to the skin

renderSkinAsString

String renderSkinAsString(<String> skin, <Object> params)

Renders a skin of a HopObject and returns the result as string.

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:
skin - as String, the name of the skin to be rendered
params - as Object, optional properties to be passed to the skin

Returns:
String containing the result of the rendered skin

setParent

void setParent(<HopObject> subnode)

Assigns a HopObject as parent to a subnode.

Sometimes it is necessary to set a subnode's parent to a certain HopObject. This is caused by the way Helma is caching subnodes.

This is the case, e.g. when you are retrieving a subnode from a relational database through different ways (e.g. by using subnode relations) and you want to remove this subnode or apply the href() function on it.

Example:  

 var trash = user.stories.get(23);
 trash.setParent(root);
 root.remove(trash);

Parameters:
subnode - as HopObject

size

Number size()

Get the number of subnodes attached to this HopObject.

Example:

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

Returns:
Number of subnodes

See:
- count()

skin_macro

void skin_macro(param)

macro rendering a skin or displaying its source (param.as == "source")

switch_macro

void switch_macro(param)

this macro renders a text depending on the value of a given property

update

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