r9710 - apps/reference/trunk/coreEnvironment

Author: zumbrunn
Date: 2009-05-05 21:46:11 +0200 (Tue, 05 May 2009)
New Revision: 9710

Modified:
   apps/reference/trunk/coreEnvironment/HopObject.js
Log:
added docs for HopObject.getCollection()

Details at http://dev.helma.org/trac/helma/changeset/9710

Modified: apps/reference/trunk/coreEnvironment/HopObject.js
===================================================================
--- apps/reference/trunk/coreEnvironment/HopObject.js	2009-05-05 12:35:02 UTC (rev 9709)
+++ apps/reference/trunk/coreEnvironment/HopObject.js	2009-05-05 19:46:11 UTC (rev 9710)
@@ -305,6 +305,56 @@
 
 
 /**
+ * Returns a collection of HopObjects as defined by
+ * a provided properties object.
+ * <br /><br />
+ * 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.
+ * <br /><br />
+ * Examples:
+ * <pre>var c = Page.getCollection({
+ * &nbsp;&nbsp;order: "name",
+ * &nbsp;&nbsp;filter: "id > 10",
+ * };</pre>
+ * You can also specify the type of contained objects using  
+ * the "collection" property, so the following collection is 
+ * equivalent to the one defined above:
+ * <pre>var c = HopObject.getCollection({
+ * &nbsp;&nbsp;collection: "Page",
+ * &nbsp;&nbsp;order: "name",
+ * &nbsp;&nbsp;filter: "id > 10",
+ * };</pre>
+ * Note that for "nested" properties such as group.order or 
+ * local.1 you have to use quoted "flat" properties, not 
+ * nested objects:
+ * <pre>var c = Page.getCollection({
+ * &nbsp;&nbsp;group: "author",
+ * &nbsp;&nbsp;"group.order": "author",
+ * &nbsp;&nbsp;"group.prototype": "AuthorGroup"
+ * });</pre>
+ * 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:
+ * <pre>var q = Page.getCollection({
+ * &nbsp;&nbsp;limit: 10,
+ * &nbsp;&nbsp;offset: 10
+ * });</pre>
+ * Note that "limit" is just an alias for "maxSize" introduced 
+ * to be more consistent with the underlying SQL syntax.
+ * <br /><br />
+ * This feature is currently implemented and known to work 
+ * on MySQL, Postgresql, and Oracle.
+ * 
+ * @param {Object} props as Object, properties defining the desired collection
+ * @return Array the collection of HopObjects as defined by the provided properties
+ * @type Array
+ */
+HopObject.getCollection = function(props) {};
+
+
+/**
  * Optional handler to override the default URL path resolution.
  * <br /><br />
  * If defined, the getChildElement() method is called on an 
@@ -325,7 +375,7 @@
  * &nbsp;&nbsp;else {
  * &nbsp;&nbsp;&nbsp;&nbsp;return this.get(name);
  * &nbsp;&nbsp;}
- * }
+ * }</pre>
  * 
  * @param {String} name as String, the name of the child element in the requested URL path
  * @return HopObject the child object to be used for further path resolution