Index: openacs-4/packages/acs-tcl/tcl/form-processing-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-tcl/tcl/form-processing-procs.tcl,v
diff -u -r1.16.2.20 -r1.16.2.21
--- openacs-4/packages/acs-tcl/tcl/form-processing-procs.tcl 14 Jul 2003 13:34:39 -0000 1.16.2.20
+++ openacs-4/packages/acs-tcl/tcl/form-processing-procs.tcl 25 Jul 2003 18:50:55 -0000 1.16.2.21
@@ -18,10 +18,12 @@
- We use the standard ATS form builder's form and element create procedures to generate forms,
- and its state-tracking code to determine when to execute various code blocks. Because of
- this, you can use any form builder datatype or widget with this procedure, and extending its
- functionality is a simple matter of implementing new ones.
+ We use the standard OpenACS Templating System (ATS) form builder's form and element create
+ procedures to generate forms, and its state-tracking code to determine when to execute
+ various code blocks. Because of this, you can use any form builder datatype or widget
+ with this procedure, and extending its functionality is a simple matter of implementing
+ new ones. Because ad_form is just a wrapper for the ATS, you must familiarize
+ yourself with it to be able to use ad_form effectively.
@@ -150,10 +152,39 @@
being served.
+
-actions
+
A list of lists of actions (e.g. {{" Delete " delete} {" Resolve " resolve}} ), which gets
+ translated to buttons at the bottom of the form. You can find out what button was pressed
+ with [template::form get_action form_id], usually in the -edit_request block to perform whatever
+ actions you deem appropriate. When the form is loaded the action will be empty.
+
+
+ -mode { display | edit }
+
If set to 'display', the form is shown in display-only mode, where the user cannot edit the fields.
+ Each widget knows how to display its contents appropriately, e.g. a select widget will show
+ the label, not the value. If set to 'edit', the form is displayed as normal, for editing.
+ Defaults to 'edit'. Switching to edit mode when a button is clicked in display mode is handled
+ automatically
+
+
+ -has_edit { 0 | 1 }
+
Set to 1 to suppress the Edit button automatically added by the form builder. Use this if you
+ include your own.
+
+
+ -form
+
Declare form elements (described in detail below)
+
+
-cancel_url
-
The URL the cancel button should take you to. If this is specified, a cancel button will show up.
+ The URL the cancel button should take you to. If this is specified, a cancel button will show up.
+ during the edit phase.
+ -cancel_label
+
The label for the cancel button.
+
+
-html
The given html will be added to the "form" tag when page is rendered. This is commonly used to
define multipart file handling forms.
@@ -166,17 +197,6 @@
similar flags are not allowed though it would be good to do so in the future.
- -form
-
Declare form elements (described in detail below)
-
-
- -on_request
-
A code block which sets the values for each element of the form meant to be modifiable by
- the user when the built-in key management feature is being used or to define options for
- select lists etc. You just need to set the values as local
- variables in the code block, and they'll get fetched and used as element values for you.
-
-
-select_query
Defines a query that returns a single row containing values for each element of the form meant to be
modifiable by the user. Can only be used if an element of type key has been declared.
@@ -190,11 +210,25 @@
declared
+ -show_required_p { 0 | 1 }
+
Should the form template show which elements are required. Use 1 or t for true, 0 or f for false.
+ Defaults to true.
+
+
+ -on_request
+
A code block which sets the values for each element of the form meant to be modifiable by
+ the user when the built-in key management feature is being used or to define options for
+ select lists etc. Set the values as local variables in the code block, and they'll get
+ fetched and used as element values for you. This block is executed everytime the
+ form is loaded except when the form is being submitted (in which case the -on_submit
+ block is executed.)
+
+
-edit_request
A code block which sets the values for each element of the form meant to be modifiable by the user. Use
this when a single query to grab database values is insufficient. Can only be used if an element of
type key is defined. This block is only executed if the page is called with a valid key, i.e. a
- self-submit form to add or edit an item called to edit the data. You just need to set the values as local
+ self-submit form to add or edit an item called to edit the data. Set the values as local
variables in the code block, and they'll get fetched and used as element values for you.