[Checkins] SVN: zc.extjs/branches/dev/src/zc/extjs/resources/util. Added documentation for the form_panel function.

[Gintautas Miliauskas]

Log message for revision 85085:
  Added documentation for the form_panel function.
  
  This should cover the last of Jim's notes on my initial changes.
  

Changed:
  U   zc.extjs/branches/dev/src/zc/extjs/resources/util.js
  U   zc.extjs/branches/dev/src/zc/extjs/resources/util.txt

-=-
Modified: zc.extjs/branches/dev/src/zc/extjs/resources/util.js
===================================================================
--- zc.extjs/branches/dev/src/zc/extjs/resources/util.js	2008-04-03 21:44:39 UTC (rev 85084)
+++ zc.extjs/branches/dev/src/zc/extjs/resources/util.js	2008-04-03 21:55:54 UTC (rev 85085)
@@ -91,16 +91,8 @@
         return form;
     }
 
-    function form_panel(args, callback)
+    function form_panel(args)
     {
-        // Create a form panel by loading a description of the fields.
-        // `args` is a dict of options; make sure to specify `url`.
-        //
-        // This function is asynchonous!  It returns immediately, and
-        // calls `callback` with the newly constructed form panel only
-        // when it is ready.  Normally the callback would add the panel
-        // to some container.  Remember to call container.doLayout()
-        // after adding the component.
         call_server({
             url: args.url,
             params: args.params,
@@ -137,7 +129,7 @@
                 });
 
                 form_reset(formpanel, result.data);
-                callback(formpanel);
+                args.callback(formpanel);
             }
         });
     }
@@ -270,7 +262,6 @@
     return {
         call_server: call_server,
         new_form: new_form,
-        get_form_config: get_form_config,
         form_dialog: form_dialog,
         form_panel: form_panel,
         form_failure: form_failure,

Modified: zc.extjs/branches/dev/src/zc/extjs/resources/util.txt
===================================================================
--- zc.extjs/branches/dev/src/zc/extjs/resources/util.txt	2008-04-03 21:44:39 UTC (rev 85084)
+++ zc.extjs/branches/dev/src/zc/extjs/resources/util.txt	2008-04-03 21:55:54 UTC (rev 85085)
@@ -44,7 +44,7 @@
 The function doesn't return anything.
 
 new_form(config)
-============
+================
 
 Create a form panel using a form definition loaded from a formlib-based
 server form.
@@ -94,7 +94,6 @@
     configuration parameters to be passed when creating a form
     panel within the dialog
 
-
 after (optional)
     A Callback function to call when a form has been successfully
     submitted without errors.
@@ -132,11 +131,54 @@
        }).createDelegate(this, [])
    });
 
+form_panel(config)
+==========================
 
+Asynchronously create a form panel by loading formlib-based form definitions
+from a server.
+
+The arguments are given as a configuration argument with items:
+
+url
+  The URL to load the definitions from.
+
+window_config
+  A configuration object giving extra window configuration data.  This
+  should generally include:
+
+  title
+     The window title
+
+  width
+     The window width
+
+     Ext seems to be able to calculate the window height OK, but not
+     the window width.
+
+form_config
+    configuration parameters to be passed when creating a form
+    panel within the dialog
+
+after (optional)
+    A Callback function to call when a form has been successfully
+    submitted without errors.
+
+callback
+    Function to call after the form panel has been created.
+
+This function does not return a form panel.  Instead, it submits
+an asynchronous request of the form definition to the server.
+When a reply is received, the actual form panel is created, and
+the provided callback is invoked with the new form panel as an argument.
+Normally the callback would add the panel to a container.
+
+Remember to invoke container.doLayout() if you add the form panel to a
+component that may already be visible.
+
 form_failure(form, action)
 ==========================
 
-This is a generic failure handler that can be used to failed form submissions.
+This is a generic failure handler that can be used for failed form submissions.
 
 If the action.result object has a true session_expired attribute, it
 will display a notification to the user that they need to log in again