1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
\r
4 <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
5 <title>Rico LiveGrid Forms</title>
\r
6 <link href="ricoDocs.css" rel="Stylesheet" type="text/css">
10 <h1>Using Rico LiveGrid Forms</h1>
\r
14 <p>While this document just refers to ASP, identical functionality is provided
\r
15 by the PHP and .net plugins.
\r
18 <li>create a new ASP file that includes ricoLiveGridForms.vbs
\r
20 <li>in the new ASP, define each of the fields in the table to be edited - usually 1-3 lines of code per field
\r
22 <li>the resulting ASP not only creates the appropriate grid, but also generates an input form in a hidden div
\r
24 <li>the ASP also adds "add/edit/delete record" entries to the popup menu
\r
26 <li>when add or edit is chosen, the form is unhidden (and filled in if edit was chosen)
\r
28 <li>when the user hits the save button, the form silently posts back to the original ASP
\r
30 <li>the ASP saves the data to the database and sends a response back to the client
\r
32 <li>the client displays a success or failure message in the bookmark area
\r
35 <p>The following two diagrams shows how requests and responses flow with LiveGrid Forms pages,
\r
36 and with LiveGrid pages without forms.
\r
37 While the two diagrams are labelled ASP/PHP, they also apply to .net (except that there is no dbClass2 in .net).
\r
38 <p><img src='images/asp-php-structure1.jpg'>
\r
39 <p><img src='images/asp-php-structure2.jpg'>
\r
44 <p>This class provides all of the functions necessary to view, insert, update, and delete
\r
45 records on a single table. An ASP script should follow these steps:
\r
48 <li>Create a single instance of the class
\r
49 <pre>set oForm=new TableEditClass</pre>
\r
51 <li>call the SetTableName method
\r
52 <pre>oForm.SetTableName "customer"</pre>
\r
54 <li>optionally set the CanAdd, CanEdit, CanDelete, ConfirmDelete, and/or RecordName properties if desired
\r
56 oForm.options("canAdd")=CanAdd
\r
57 oForm.options("canEdit")=CanModify
\r
58 oForm.options("canDelete")=CanDelete
\r
60 <li>if TableName is a view or has no primary key defined, editing will be disabled
\r
61 <li>call AddEntryField or AddCalculatedField for each field/column to be displayed
\r
62 Fields appear in both the table and form views, with the following exceptions:
\r
64 <li>entry type is H never gets sent to the client. Writes to the database get the defined default value.
\r
65 <li>if FormView field property is set to "exclude", then the field appears in the table only.
\r
66 <li>if FormView field property is set to "hidden", then the data is put in a hidden form field.
\r
67 <li>Calculated fields appear in the table view only (same as FormView=exclude)
\r
70 <li>After each call to AddEntryField or AddCalculatedField, the other methods and properties
\r
71 can be invoked to control how the field is presented to the user (e.g. SortAsc).
\r
72 Calls to these properties/methods apply only to the field most recently added.
\r
73 <li>call DisplayPage - this displays the grid or executes the database update
\r
74 <pre>oForm.DisplayPage</pre>
\r
78 <h2>TABBED FORMS</h2>
\r
80 <p>Forms with multiple panels/tabs are fully supported using the Rico.TabbedPanel class.
\r
81 Simply call AddPanel before calling AddEntryField to define the fields for that panel.
\r
84 ' these fields appear on the first panel
\r
85 oForm.AddPanel "Panel #1"
\r
86 oForm.AddEntryField "field1", "Field #1", "T", ""
\r
87 oForm.AddEntryField "field2", "Field #2", "T", ""
\r
88 oForm.AddEntryField "field3", "Field #3", "T", ""
\r
90 ' these fields appear on the second panel
\r
91 oForm.AddPanel "Panel #2"
\r
92 oForm.AddEntryField "field4", "Field #4", "T", ""
\r
93 oForm.AddEntryField "field5", "Field #5", "T", ""
\r
94 oForm.AddEntryField "field6", "Field #6", "T", ""
\r
97 <p>Alternatively, the panelIdx property can be set for each field as it is defined. In this
\r
98 case, AddPanel can be called at any time prior to DisplayPage.
\r
100 ' these fields appear on the first panel
\r
101 oForm.AddEntryField "field1", "Field #1", "T", ""
\r
102 oForm.CurrentField("panelIdx")=0
\r
103 oForm.AddEntryField "field2", "Field #2", "T", ""
\r
104 oForm.CurrentField("panelIdx")=0
\r
105 oForm.AddEntryField "field3", "Field #3", "T", ""
\r
106 oForm.CurrentField("panelIdx")=0
\r
108 ' these fields appear on the second panel
\r
109 oForm.AddEntryField "field4", "Field #4", "T", ""
\r
110 oForm.CurrentField("panelIdx")=1
\r
111 oForm.AddEntryField "field5", "Field #5", "T", ""
\r
112 oForm.CurrentField("panelIdx")=1
\r
113 oForm.AddEntryField "field6", "Field #6", "T", ""
\r
114 oForm.CurrentField("panelIdx")=1
\r
116 oForm.AddPanel "Panel #1"
\r
117 oForm.AddPanel "Panel #2"
\r
121 <h2>FORM METHODS</h2>
\r
123 <dt>AddPanel "Panel Heading"
\r
124 <dd>Defines the heading for a tabbed panel on the input form.
\r
127 <dd>Displays the grid or updates the database depending on the value of "action".
\r
129 <dt><a name='DefineAltTable'></a>DefineAltTable (TableName, FieldList, FieldData, Delim)
\r
130 <dd>Function that returns a TabId to be used in subsequent <a href='#AltTable'>AltTable</a> calls.
\r
131 Defines a secondary table to store additional, related fields.
\r
132 Key field(s) in main table must also exist in AltTable.
\r
133 FieldList & FieldData are delimited strings that define
\r
134 additional, constant values/functions to be stored in the secondary table.
\r
135 Delim specifies the delimiter character used in FieldList & FieldData.
\r
136 FieldList & FieldData must contain the same number of delimited entries.
\r
139 <dd>Call to generate pure XHTML output.
\r
141 <dt>SetDbConn (dbcls)
\r
142 <dd>Specifies the instance of dbClass to be used.
\r
143 If a global instance named oDB exists, then it will be used without this method having to be called.
\r
147 <h2>FORM PROPERTIES</h2>
\r
149 <p>All <a href="LiveGrid.html#options">LiveGrid</a> options are supported as properties, in addition to these which are specific to LiveGrid Forms.
\r
153 <dt>action (read only)
\r
154 <dd>specifies the current action being performed: table, ins, upd, del
\r
156 <dt>gridVar (read only)
\r
157 <dd>returns the name of the client-side LiveGrid object
\r
159 <dt>bufferVar (read only)
\r
160 <dd>returns the name of the client-side LiveGrid Buffer object
\r
163 <dd>automatically initialize the grid (create the data rows)
\r
166 <dt>InitScript (read only)
\r
167 <dd>returns the javascript code (as a string) to initialize the grid (use when AutoInit is false)
\r
170 <dd>specifies a where clause to be used in table view (optional)
\r
172 // only show records for the logged in user
\r
173 $oForm->TableFilter = "userid=$myuserid";
\r
177 <dd>allow user to add new records, defaults to true
\r
179 <dd>allow user to edit records, defaults to true
\r
181 <dd>allow user to delete records, defaults to true
\r
183 <dd>allow user to clone records (edit existing record but save as new), defaults to false
\r
186 <dd>Extend the grid with LiveGrid Forms -- data entry form is created, add/edit/delete items are
\r
187 added to the grid menu, etc. Default is true in ASP and PHP, false in .net.
\r
190 <dd>post updates back to this location, defaults to the page that generated the grid
\r
193 <dd>flag specifying whether a confirmation popup should be displayed
\r
194 after the user clicks the delete button, defaults to true
\r
195 (see also <a href='#ConfirmDeleteCol'>ConfirmDeleteCol</a>)
\r
198 <dd>displaying debugging messages, defaults to false
\r
201 <dd>string to customize add, edit, and delete title tags,
\r
202 defaults to "Record"
\r
205 <dd>Text box width. default is 20.
\r
207 <dt>TableName (write only)
\r
208 <dd>the table or view to be displayed/edited (required)
\r
211 <dd>String used to identify when a user has selected to create a new value
\r
212 for an EntryType N field. Default is "___new___".
\r
215 <dd>Disposition of database update responses:
\r
217 <li>full - show full response
\r
218 <li>errors - show full response for errors and short response otherwise (default)
\r
222 <dt style='color:navy;'><em>When using tabbed panels on the input form:</em>
\r
225 <dd>Width of tabbed panels in pixels. Default is 500.
\r
228 <dd>Height of tabbed panels in pixels. Default is 200.
\r
231 <dd>CSS class when hovering over panel tab. Default is "tabHover".
\r
234 <dd>CSS class when panel tab is selected. Default is "tabSelected".
\r
239 <h2>FORM EVENTS</h2>
\r
241 <p>It is possible to hook into several form events.
\r
245 <dd>Fires when the input form is displayed.
\r
247 oForm.options("formOpen")=
\r
248 "alert('Questions? Please call the support desk.');"
\r
252 <dd>Fires right after the input form is closed.
\r
254 <dt>onSubmitResponse
\r
255 <dd>Fires after a form has been sent to the server and a response has been received and processed.
\r
260 <h2>FIELD DEFINITION-METHODS</h2>
\r
262 <dt>AddEntryField (ColumnName, Heading, EntryTypeCode, DefaultValue)
\r
263 <dd>Adds a new column to the grid and a new entry field to the popup form in ASP and PHP.
\r
267 <dd>column name in the database table (does not support blanks or any name that would require square brackets in SQL, e.g. [Apr 2005])
\r
270 <dd>name that appears on the grid column's heading and also on the popup form
\r
273 <dd>string containing a code that controls how the column is displayed on the input form
\r
276 <li><strong>S</strong>:
\r
277 Display this column as a drop-down select list during data entry.
\r
278 Values may be specified using the "SelectValues" or "SelectSql" options.
\r
279 If neither is specified, then the values for the column are obtained using
\r
280 a "select distinct" query.
\r
281 <li><strong>R</strong>: Same as "S", except the items are displayed using radio buttons.
\r
282 <li><strong>SL,RL</strong>:
\r
283 Same as S & R, except that a lookup value is displayed in table view
\r
284 (uses query specified by SelectSql).
\r
285 Typically used on columns that are foreign keys. SQL to get the display value
\r
286 is specified using the "SelectSql" option.
\r
287 <li><strong>CL</strong>: Same as "SL", except that the value is selected
\r
288 using a custom control (such as the Rico Tree control).
\r
289 The SelectCtl option must be assigned the id of the custom control.
\r
290 <li><strong>N</strong>:
\r
291 Same as "S", but allows the user to create a new value.
\r
292 Typically used <em>without</em> the "SelectValues" or "SelectSql" options.
\r
293 <li><strong>H</strong>: column is hidden from the user (DefaultValue will be stored in the table on adds and edits)
\r
294 <li><strong>D</strong>: this is a date field (blanks allowed if column allows nulls)
\r
295 <li><strong>DT</strong>: same as D, except that it also includes the time
\r
296 <li><strong>I</strong>: integer number (blanks allowed if column allows nulls and required is false)
\r
297 <li><strong>F</strong>: floating-point number (blanks allowed if column allows nulls and required is false)
\r
298 <li><strong>B</strong>: non-blank text field (user gets a popup message in form view when clicking save and the field is empty)
\r
299 <li><strong>T</strong>: standard text field (blanks allowed)
\r
300 <li><strong>TA</strong>: text area field
\r
301 <li><strong>tinyMCE</strong>: rich text edit field using the
\r
302 <a href="http://tinymce.moxiecode.com/">tinyMCE</a> library.
\r
306 <dd>column's default value in the form view
\r
309 <p>The equivalent to AddEntryField() in .net is to declare column fields as part of the markup.
\r
310 The "ColData" attribute contains the default value.
\r
311 Here is an example from ex2edit.aspx:
\r
313 <Rico:Column runat='server' heading='Order#' width='60'
\r
314 ColName='OrderID' EntryType='B' ColData='<auto>' />
\r
317 <dt>AddEntryFieldW (ColumnName, Heading, EntryTypeCode, DefaultValue, ColWidth)
\r
318 <dd>Same as AddEntryField except an extra parameter is added for column width (in pixels).
\r
320 <dt>AddCalculatedField (ColumnFormula, Heading)
\r
321 <dd>ColumnFormula is any valid SQL expression or subquery.
\r
322 If the subquery needs to reference a column in the table being displayed,
\r
323 then the column name should be prefaced with the alias "t."
\r
324 Calculated fields will be displayed in table view, but not in form view.
\r
326 <dt>AddFilterField (ColumnName, FilterValue)
\r
327 <dd>Only display records where the contents of ColumnName=FilterValue.
\r
328 This becomes a hidden field (entry type H).
\r
330 <dt><a name='ConfirmDeleteCol'></a>ConfirmDeleteCol (ConfirmDeleteColumn in .net plug-in)
\r
331 <dd>The text content of the column will be included in delete confirmation messages
\r
334 <dd>In table view, sort by this column in ascending order (applies to most recently added field)
\r
337 <dd>In table view, sort by this column in descending order (applies to most recently added field)
\r
342 <h2>FIELD DEFINITION-PROPERTIES</h2>
\r
344 <p>All <a href="LiveGrid.html#column">LiveGrid</a> column properties are supported, in addition to these which are specific to LiveGrid Forms.
\r
349 <dd>When false, the column value will be left unquoted when inserting or updating
\r
350 the database (default=true). This makes it possible to populate columns with
\r
351 SQL function calls. For example:
\r
353 oForm.AddEntryField "LastEditUser","","H","suser_sname()"
\r
354 oForm.CurrentField("AddQuotes")=false
\r
355 oForm.AddEntryField "LastEditDate","","H","getdate()"
\r
356 oForm.CurrentField("AddQuotes")=false
\r
360 <dd>Boolean value that specifies whether the input field may be left empty
\r
361 (default: false if column allows nulls and EntryType is not "B", true otherwise).
\r
364 <dd>Boolean value that when true, specifies that this entry field should placed on the same form row as the last field
\r
365 (default: false - each form field is place on a separate row).
\r
367 <dt><a name='AltTable'></a>AltTable (TabId)
\r
368 <dd>Specifies that the field should be stored in an alternate table
\r
369 TabId should be the value returned by a previous call to <a href='#DefineAltTable'>DefineAltTable</a>
\r
372 <dd>For columns with entry type "TA", this is # of rows to display in the
\r
373 textarea when in form view (default 4)
\r
376 <dd>For columns with entry type "TA", this is # of columns to display in the
\r
377 textarea when in form view (default 80)
\r
380 <dd>If true, then the grid is filtered by the default value for this column (default=false)
\r
383 <dd>Creates a title tag containing the specified text (form view only). So if the user
\r
384 hovers over the field label, they will see this text as balloon help. For example:
\r
386 oForm.CurrentField("Help")="Date must be entered in mm/dd/yyyy format"
\r
390 <dd>A string containing a regular expression. User entries will be checked to ensure
\r
391 they match the pattern specified. There are a few special values:
\r
393 <li>"email" - tests for a valid email address
\r
394 <li>"float-unsigned" - tests for a valid unsigned floating point (real) number
\r
395 <li>"float-signed" - tests for a valid signed floating point (real) number (this is the default when EntryType is "F")
\r
396 <li>"int-unsigned" - tests for a valid unsigned integer number
\r
397 <li>"int-signed" - tests for a valid signed integer number (this is the default when EntryType is "I")
\r
399 <br>It is recommended that a Help entry be included
\r
400 whenever a pattern is specified. If the field fails validation, the help text
\r
401 will be included in the error message presented to the user. For example:
\r
403 oForm.CurrentField("Help")="Enter date as mm/dd/yyyy"
\r
404 oForm.CurrentField("pattern")="^\\d{1,2}/\\d{1,2}/\\d{4}$"
\r
408 <dd>Specifies the minimum/maximum allowable values for fields with EntryType "I", "F", and "D".
\r
411 oForm.AddEntryField "field1", "Field #1", "I", "0"
\r
412 oForm.CurrentField("min")=1
\r
413 oForm.CurrentField("max")=10
\r
414 oForm.CurrentField("Help")="Enter a value between 1 and 10"
\r
416 oForm.AddEntryField "field2", "Field #2", "D", Date()
\r
417 oForm.CurrentField("min")="2000-01-01"
\r
418 oForm.CurrentField("max")="2099-12-31"
\r
419 oForm.CurrentField("Help")="Enter a value in the 21st century!"
\r
423 <dd>Only write this field to the database when peforming an insert (default=false).
\r
425 oForm.AddEntryField "CreateDate","","H","getdate()"
\r
426 oForm.CurrentField("AddQuotes")=false
\r
427 oForm.CurrentField("InsertOnly")=true
\r
431 <dd>Only write this field to the database when peforming an update (default=false).
\r
433 oForm.CurrentField("UpdateOnly")=true
\r
437 <dd>If true, data is displayed on the entry form but cannot be changed, text is gray (default=false).
\r
438 Does not apply to entry types of S, SL, N, R, RL -- use objTE.CurrentField("FormView")="hidden" instead.
\r
441 <dd>Specifies the choices the user sees in form view for EntryTypes of N, S, and R.
\r
442 If supplied, then this should be a string of comma-separated values. For example:
\r
444 oForm.CurrentField("SelectValues")="Y,N"
\r
448 <dd>Specifies the SQL select statement to use for EntryTypes of SL, CL, and RL.
\r
449 The select statement should return 2 columns: the first being the code
\r
450 and the second being the text value/description. For example:
\r
452 oForm.CurrentField("SelectSql")="select ID,Name from Customers"
\r
456 <dd>SelectSql serves 2 purposes. First, it is used to retrieve the appropriate
\r
457 data to display in the grid. Second, it is used to populate the values in
\r
458 the select box (SL) or radio buttons (RL) on the pop-up form. In some cases,
\r
459 you may want these to be different. In the SelectSql example above, we
\r
460 are retrieving customer name. But let's say that our Customers table has
\r
461 a "CreditHold" field and we want to disable the selection of customers on
\r
462 credit hold in the form view, but still display them in the grid.
\r
463 This is where SelectFilter comes in:
\r
465 oForm.CurrentField("SelectFilter")="CreditHold='NO'"
\r
projects / infodrom / rico3 / blob