Tuesday, December 4, 2007

The _parent entry contains a comma-separated list of properties of objects of this type to be used as parent. Objects must know their parent in order to generate correct URLs in their href() function.

_parent = property1, property2.collectionX, root.collectionY

If an entry in the _parent item does not contain a dot, it is interpreted as an object property of the current object that acts as the object's parent. If an entry contains a dot character, the part after the dot is interpreted as a collection in the parent object in which the current object is contained. If the _parent is specified as "root", it is not interpreted as a property of the current object. Instead, the application's root object is used as parent object.

Hrrrwhat?

This is confusing, because _parent is a very specific and tacked on solution to a very specific problem with how helma is architected.

Helma works by mapping a javascript object graph to a url space. Helma lets you map the same object or collection of objects to more than one part of the URL space. There frequently comes a situation where you'll want to generate a link on an html page to a specific object: Say you have a wiki page with a link, and an object representing the page it links to. You'd want to be able to generate the URL to that linked to page on the fly.

Helma provides a function on each object: the href function. This href automatically generates a URL which points at the object that it's called on. So for instance, root.wiki.pages[547].href() may return the url /wikiprogram/wiki/pages/547/. The problem is that an object has no way of knowing which url you want, if it can be accessed by more than one url.

The problem comes when that page 547 is also in another collection. Say, root.wiki.history.pages[547]

Which url should href return? /wikiprogram/wiki/pages/547/ or /wikiprogram/wiki/history/pages/547/ ?

What helma does is pick whichever url that you access the object from *first*, after the application is started, and use that URL henceforth. That is, unless you specify _parent in type.properties.

So, in the page prototype's type.properties file you can add

_parent = root.wiki

and the href function for that object will always return /wikiprogram/wiki/pages/547/

if instead you specify

_parent = root.wiki.history

then the result will always be /wikiprogram/wiki/history/pages/547/

Thus, _parent lets you choose the canonical URL for an object.

The documentation quoted above appears to indicate that _parent can do more than this, but that is something that will have to wait for another post, since I have not yet deduced what that is.