Rabbit 1.1

.jsdoc/HopObject.js

Summary

Default fields and methods of the HopObject class.


Class Summary
HopObject Extends the standard JavaScript object with Helma-specific properties and functions.

//
// Copyright (c) 2006 Tobi Schäfer
// Alle Rechte vorbehalten. All rights reserved.
//
// $Revision: 446 $
// $LastChangedBy: tobi $
// $LastChangedDate: 2007-02-15 20:59:15 +0100 (Thu, 15 Feb 2007) $
// $HeadURL: http://p3k.org/source/rabbit/trunk/docs/overview-summary-.jsdoc_HopObject.js.html $
//

/**
 * @fileoverview Default fields and methods of the HopObject class.
 */

/**
 * Constructs a new HopObject.
 * @class 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 any custom type defined 
 * by the application are HopObjects and inherit all
 * functionality described below.
 * <p>In addition to defining and scripting your individual 
 * types of HopObjects it is possible to extend all your 
 * prototypes that are derived from HopObject by adding a 
 * "HopObject" directory to your application.</p>
 * @constructor
 */
function HopObject() {
   /**
    * Object providing space for arbitrary run-time data (object cache).
    * Each HopObject contains a cache object to store temporary properties
    * (strings, numbers, objects etc.).
    * These properties can be accessed in any thread until the application
    * is restarted or the HopObject is invalidated, either manually using
    * invalidate function or whenever Helma is updating the HopObject's data
    * from a remote database.
    * There is no way to make the cache object persistent.
    * @type HopObject
    */
   this.cache = null;

   /**
    * The unique id of the HopObject.
    * This property is read-only
    * @readonly
    * @type Number
    */
   this._id = null;

   /**
    * The parent collection containing the HopObject.
    * @type HopObject
    */
   this._parent = null; 

   /**
    * The prototype of a HopObject.
    * @type String
    */
   this._prototype = null;

   /**
    * Adds a HopObject as new subnode to another HopObject.
    * The new subnode is added after the last subnode already 
    * contained in the parent HopObject.
    * @param {HopObject} object The HopObject to be added.
    * @returns True if the addition was successful.
    * @type Boolean
    */
   this.add = function(object) {};

   /**
    * Adds a HopObject as subnode to a HopObject at a certain position.
    * Unlike {@link #add} the position of the subnode is determined
    * by the number argument in the function call.
    * Using this function usually only has an effect with the embedded
    * database, since the order of objects stored in a relational database
    * depends on the value of some table column. Thus, when adding objects
    * stored in a relational database, one may as well use add().
    * @param {Number} position The position a new HopObject should
    * be added at.
    * @param {HopObject} object The HopObject to be added.
    * @returns True if the addition was successful.
    * @type Boolean
    */
   this.addAt = function(position, object) {};

   this.clearCache = function() {};

   /**
    * 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.
    * @param {HopObject} object The desired HopObject.
    * @returns The index position of the subnode or -1.
    * @type Number
    */
   this.contains = function(object) {};

   /**
    * <strong><em>DEPRECATED.</em></strong>
    * @deprecated Use {@link #size}, instead.
    */
   this.count = function() {};

   /**
    * Returns an HTML input element for a HopObject property.
    * The result of this function call can be used inside an HTML form. The
    * property's value is set to the form elements value. If the optional
    * height parameter is set, a text area is used instead of a one-line
    * text field.
    * Note: Currently, the markup output does not conform to up-to-date HTML
    * specifications (like XHTML).
    * @param {String} name The name of the property.
    * @param {Number} width The width of the input element.
    * @param {Number} height The height of the input element.
    * @returns The rendered HTML element for the property.
    * @type String
    */
   this.editor = function(name, width, height) {};

   /**
    * Retrieves a property or a subnode of a HopObject.
    * 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 the corresponding property of
    * the HopObject.
    * Finally, a number as string retrieves the subnode with the
    * corresponding Hop ID.
    * @param {Object} id The name of the property or  hte ID of the 
    * desired HopObject. This can be a number (e.g. 12), a string 
    * ("twelve") or a number as string ("12").
    * @returns The desired property or HopObject.
    */
   this.get = function(id) {};

   /**
    * Retrieves a HopObject by its ID.
    * @param {Number} id The ID of the desired HopObject.
    * @returns The desired HopObject.
    * @type HopObject
    */
   this.getById = function(id) {};

   /**
    * Handle Helma's request for a HopObject's subnode.
    * 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.
    * @param {String} name The name of the child element.
    * @returns A persistent HopObject.
    * @type HopObject
    */
   this.getChildElement = function(name) {};

   /**
    * Returns the absoulte URL path of a HopObject relative to the
    * application's root. An optional string argument is simply
    * appended to the return value.
    * This function is useful when referring to a HopObject 
    * from within HTML (e.g. in an link element).
    * @param {String} action An optional action that will be
    * appended to the URL string.
    * @returns The resulting URL.
    * @type String
    */
   this.href = function(action) {};

   /**
    * 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.^
    * @returns True if the invalidation was successful.
    * @type Boolean
    */
   this.invalidate = function() {};

   /**
    * Returns an array of subnodes of a HopObject.
    * The start and end 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.
    * @param {Number} start The index position of the first subnode.
    * @param {Number} end The index position of the last subnode.
    * @returns The resulting list of subnodes.
    * @type Array
    */
   this.list = function(start, end) {};

   /**
    * Handle Helma requests for the HopObject.
    * The onRequest handler 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.
    */
   this.onRequest = function() {};

   /**
    * 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.
    * @returns The ID of the persistent HopObject.
    * @type Number
    */
   this.persist = function() {};

   /**
    * Manually retrieve 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.
    * @param {Number} start The index position of the first
    * subnode to be retrieved.
    * @param {Number} length The number of subnodes to be fetched.
    */
   this.prefetchChildren = function(start, length) {};

   /**
    * 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 {@link #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.
    */
   this.remove = function() {};

   /**
    * 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 {@link #remove} on the child
    * object in order to delete it from the database.
    */
   this.removeChild = function(object) {};

   /**
    * Renders a skin of a HopObject and writes the result to the output.
    * 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.
    * @param {String} name The name of the skin to be rendered.
    * @param {Object} param Extra HopObject macro parameters.
    */
   this.renderSkin = function(name, param) {};

   /**
    * Renders a skin of a HopObject and returns the result.
    * @param {String} name The name of the skin to be rendered.
    * @param {Object} param Extra HopObject macro parameters.
    * @returns The rendered skin.
    * @type String
    * @see #renderSkin
    */
   this.renderSkinAsString = function(name, param) {};

   /**
    * 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 {@link #href}
    * function on it.
    * @param {HopObject} object The parent of the HopObject.
    */
   this.setParent = function(object) {};

   /**
    * Get the number of subnodes contained by the HopObject.
    * @returns The number of subnodes.
    * @type Number
    */
   this.size = function() {};
}

/** @ignore JSDoc bug */
HopObject.getById = function(id) {};

Rabbit 1.1

Documentation generated by JSDoc on Thu Feb 15 20:58:41 2007