OpenACS

donb
committed
MAIN:donb:20020926235518
on 27 Sep 02
Added additional documentation ...
/tcl/form-processing-procs.tcl (+7 -5)
106 106     The call to ad_return_template then renders the page - it is your responsibility to render the form
107 107     in your template by use of the ATS formtemplate tag.
108 108  
109 109     <p>
110 110
111 111     On submission, the validation block checks that the user has entered at least three characters into the
112 112     textarea (yes, this is a silly example).  If the validation check fails the "value" element will be tagged
113 113     with the error message, which will be displayed in the form when it is rendered.
114 114
115 115     If the validation check returns true, one of the new_data or edit_data code blocks will be executed depending
116 116     on whether or not "my_table_key" was defined during the initial request.  "my_table_key" is passed as a hidden
117 117     form variable and is signed and verified, reducing the opportunity for key spoofing by malicious outsiders.
118 118    
119 119     <p>
120 120
121 121     This example includes dummy redirects to a script named "somewhere" to make clear the fact that after
122 122     executing the new_data or edit_data block ad_form returns to the caller.
123 123
124 124     <p>
125 125
  126     <b>General information about parameters</b>
  127
  128     <p>Parameters which take a name (for instance "-name" or "-select_query_name") expect a simple name
  129     not surrounded by curly braces (in other words not a single-element list).  All other parameters expect
  130     a single list to be passed in.
  131     <p>
  132
126 133     Here's a complete list of switches that are supported by ad_form:
127 134
128 135     <p>
129 136
130 137     <dl>
131 138     <p><dt><b>-extend</b></dt><p>
132 139     <dd>Extend an existing form.  This allows one to build forms incrementally.  Forms are built at the
133 140         template level.  As a consequence one can write utility procs that use -extend to build form
134 141         snippets common to several data entry forms. 
135 142         <p>This must be the first switch passed into ad_form
136 143     </dd>
137 144
138 145     <p><dt><b>-name</b></dt><p>
139 146     <dd>Declares the name of the form.  Defaults to the name of the script being served.</dd>
140 147
141 148     <p><dt><b>-action</b></dt><p>
142 149     <dd>The name of the script to be called when the form is submitted.  Defaults to the name of the script
143 150         being served. 
144 151     </dd>
145 152
146 153     <p><dt><b>-html</b></dt><p>
147 154     <dd>The given html will be added to the "form" tag when page is rendered.  This is commonly used to
148 155         define multipart file handling forms.
149 156     </dd>
150 157
151       <p><dt><b>-action</b></dt><p>
152       <dd>The name of the script to be called when the form is submitted.  Defaults to the name of the script
153           being served. 
154       </dd>
155  
156 158     <p><dt><b>-export</b></dt><p>
157 159     <dd>Similar to the utility <b>export_vars</b>.  Takes a list of values to insert in the form as
158 160         "hidden" elements.   Each value is either a name, in which case the Tcl variable at the caller's
159 161         level is passed to the form if it exists, or a name-value pair.   "multiple", "array", "sign" and
160 162         similar flags are not allowed though it would be good to do so in the future.
161 163     </dd>
162 164        
163 165     <p><dt><b>-form</b></dt><p>
164 166     <dd>Declare form elements (described in detail below)
165 167     </dd>
166 168
167 169     <p><dt><b>-select_query</b></dt><p>
168 170     <dd>Defines a query that returns a single row containing values for each element of the form meant to be
169 171         modifiable by the user.
170 172     </dd>
171 173
172 174     <p><dt><b>-select_query_name</b></dt><p>
173 175     <dd>The name of a query to be looked up in the appropriate query file that returns a single row containing
174 176         values for each element of the form meant to be modifiable by the user.  In the OpenACS 4 environment this
175 177         should normally be used rather than -select_query, as query files are the mechanism used to make the