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
12 <p><a href='LiveGridForms_ja.html'><img src='images/japanese.gif' alt='View this page in Japanese'></a>
\r
13 <a href='LiveGridForms_ja.html'>View this page in Japanese</a></p>
\r
17 <p>While this document just refers to ASP, identical functionality is provided
\r
18 by the PHP and .net plugins.
\r
21 <li>create a new ASP file that includes ricoLiveGridForms.vbs
\r
23 <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
25 <li>the resulting ASP not only creates the appropriate grid, but also generates an input form in a hidden div
\r
27 <li>the ASP also adds "add/edit/delete record" entries to the popup menu
\r
29 <li>when add or edit is chosen, the form is unhidden (and filled in if edit was chosen)
\r
31 <li>when the user hits the save button, the form silently posts back to the original ASP
\r
33 <li>the ASP saves the data to the database and sends a response back to the client
\r
35 <li>the client displays a success or failure message in the bookmark area
\r
38 <p>The following two diagrams shows how requests and responses flow with LiveGrid Forms pages,
\r
39 and with LiveGrid pages without forms.
\r
40 While the two diagrams are labelled ASP/PHP, they also apply to .net (except that there is no dbClass2 in .net).
\r
41 <p><img src='images/asp-php-structure1.jpg'>
\r
42 <p><img src='images/asp-php-structure2.jpg'>
\r
47 <p>This class provides all of the functions necessary to view, insert, update, and delete
\r
48 records on a single table. An ASP script should follow these steps:
\r
51 <li>Create a single instance of the class
\r
52 <pre>set oForm=new TableEditClass</pre>
\r
54 <li>call the SetTableName method
\r
55 <pre>oForm.SetTableName "customer"</pre>
\r
57 <li>optionally set the CanAdd, CanEdit, CanDelete, ConfirmDelete, and/or RecordName properties if desired
\r
59 oForm.options("canAdd")=CanAdd
\r
60 oForm.options("canEdit")=CanModify
\r
61 oForm.options("canDelete")=CanDelete
\r
63 <li>if TableName is a view or has no primary key defined, editing will be disabled
\r
64 <li>call AddEntryField or AddCalculatedField for each field/column to be displayed
\r
65 Fields appear in both the table and form views, with the following exceptions:
\r
67 <li>entry type is H never gets sent to the client. Writes to the database get the defined default value.
\r
68 <li>if FormView field property is set to "exclude", then the field appears in the table only.
\r
69 <li>if FormView field property is set to "hidden", then the data is put in a hidden form field.
\r
70 <li>Calculated fields appear in the table view only (same as FormView=exclude)
\r
73 <li>After each call to AddEntryField or AddCalculatedField, the other methods and properties
\r
74 can be invoked to control how the field is presented to the user (e.g. SortAsc).
\r
75 Calls to these properties/methods apply only to the field most recently added.
\r
76 <li>call DisplayPage - this displays the grid or executes the database update
\r
77 <pre>oForm.DisplayPage</pre>
\r
81 <h2>TABBED FORMS</h2>
\r
83 <p>Forms with multiple panels/tabs are fully supported using the Rico.TabbedPanel class.
\r
84 Simply call AddPanel before calling AddEntryField to define the fields for that panel.
\r
87 ' these fields appear on the first panel
\r
88 oForm.AddPanel "Panel #1"
\r
89 oForm.AddEntryField "field1", "Field #1", "T", ""
\r
90 oForm.AddEntryField "field2", "Field #2", "T", ""
\r
91 oForm.AddEntryField "field3", "Field #3", "T", ""
\r
93 ' these fields appear on the second panel
\r
94 oForm.AddPanel "Panel #2"
\r
95 oForm.AddEntryField "field4", "Field #4", "T", ""
\r
96 oForm.AddEntryField "field5", "Field #5", "T", ""
\r
97 oForm.AddEntryField "field6", "Field #6", "T", ""
\r
100 <p>Alternatively, the panelIdx property can be set for each field as it is defined. In this
\r
101 case, AddPanel can be called at any time prior to DisplayPage.
\r
103 ' these fields appear on the first panel
\r
104 oForm.AddEntryField "field1", "Field #1", "T", ""
\r
105 oForm.CurrentField("panelIdx")=0
\r
106 oForm.AddEntryField "field2", "Field #2", "T", ""
\r
107 oForm.CurrentField("panelIdx")=0
\r
108 oForm.AddEntryField "field3", "Field #3", "T", ""
\r
109 oForm.CurrentField("panelIdx")=0
\r
111 ' these fields appear on the second panel
\r
112 oForm.AddEntryField "field4", "Field #4", "T", ""
\r
113 oForm.CurrentField("panelIdx")=1
\r
114 oForm.AddEntryField "field5", "Field #5", "T", ""
\r
115 oForm.CurrentField("panelIdx")=1
\r
116 oForm.AddEntryField "field6", "Field #6", "T", ""
\r
117 oForm.CurrentField("panelIdx")=1
\r
119 oForm.AddPanel "Panel #1"
\r
120 oForm.AddPanel "Panel #2"
\r
124 <h2>FORM METHODS</h2>
\r
126 <dt>AddPanel "Panel Heading"
\r
127 <dd>Defines the heading for a tabbed panel on the input form.
\r
130 <dd>Displays the grid or updates the database depending on the value of "action".
\r
132 <dt><a name='DefineAltTable'></a>DefineAltTable (TableName, FieldList, FieldData, Delim)
\r
133 <dd>Function that returns a TabId to be used in subsequent <a href='#AltTable'>AltTable</a> calls.
\r
134 Defines a secondary table to store additional, related fields.
\r
135 Key field(s) in main table must also exist in AltTable.
\r
136 FieldList & FieldData are delimited strings that define
\r
137 additional, constant values/functions to be stored in the secondary table.
\r
138 Delim specifies the delimiter character used in FieldList & FieldData.
\r
139 FieldList & FieldData must contain the same number of delimited entries.
\r
142 <dd>Call to generate pure XHTML output.
\r
144 <dt>SetDbConn (dbcls)
\r
145 <dd>Specifies the instance of dbClass to be used.
\r
146 If a global instance named oDB exists, then it will be used without this method having to be called.
\r
150 <h2>FORM PROPERTIES</h2>
\r
152 <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
156 <dt>action (read only)
\r
157 <dd>specifies the current action being performed: table, ins, upd, del
\r
159 <dt>gridVar (read only)
\r
160 <dd>returns the name of the client-side LiveGrid object
\r
162 <dt>bufferVar (read only)
\r
163 <dd>returns the name of the client-side LiveGrid Buffer object
\r
166 <dd>automatically initialize the grid (create the data rows)
\r
169 <dt>InitScript (read only)
\r
170 <dd>returns the javascript code (as a string) to initialize the grid (use when AutoInit is false)
\r
173 <dd>specifies a where clause to be used in table view (optional)
\r
175 // only show records for the logged in user
\r
176 $oForm->TableFilter = "userid=$myuserid";
\r
180 <dd>allow user to add new records, defaults to true
\r
182 <dd>allow user to edit records, defaults to true
\r
184 <dd>allow user to delete records, defaults to true
\r
186 <dd>allow user to clone records (edit existing record but save as new), defaults to false
\r
189 <dd>Extend the grid with LiveGrid Forms -- data entry form is created, add/edit/delete items are
\r
190 added to the grid menu, etc. Default is true in ASP and PHP, false in .net.
\r
193 <dd>post updates back to this location, defaults to the page that generated the grid
\r
196 <dd>flag specifying whether a confirmation popup should be displayed
\r
197 after the user clicks the delete button, defaults to true
\r
198 (see also <a href='#ConfirmDeleteCol'>ConfirmDeleteCol</a>)
\r
201 <dd>displaying debugging messages, defaults to false
\r
204 <dd>string to customize add, edit, and delete title tags,
\r
205 defaults to "Record"
\r
208 <dd>Text box width. default is 20.
\r
210 <dt>TableName (write only)
\r
211 <dd>the table or view to be displayed/edited (required)
\r
214 <dd>String used to identify when a user has selected to create a new value
\r
215 for an EntryType N field. Default is "___new___".
\r
218 <dd>Disposition of database update responses:
\r
220 <li>full - show full response
\r
221 <li>errors - show full response for errors and short response otherwise (default)
\r
225 <dt style='color:navy;'><em>When using tabbed panels on the input form:</em>
\r
228 <dd>Width of tabbed panels in pixels. Default is 500.
\r
231 <dd>Height of tabbed panels in pixels. Default is 200.
\r
234 <dd>CSS class when hovering over panel tab. Default is "tabHover".
\r
237 <dd>CSS class when panel tab is selected. Default is "tabSelected".
\r
242 <h2>FORM EVENTS</h2>
\r
244 <p>It is possible to hook into several form events.
\r
248 <dd>Fires when the input form is displayed.
\r
250 oForm.options("formOpen")=
\r
251 "alert('Questions? Please call the support desk.');"
\r
255 <dd>Fires right after the input form is closed.
\r
257 <dt>onSubmitResponse
\r
258 <dd>Fires after a form has been sent to the server and a response has been received and processed.
\r
263 <h2>FIELD DEFINITION-METHODS</h2>
\r
265 <dt>AddEntryField (ColumnName, Heading, EntryTypeCode, DefaultValue)
\r
266 <dd>Adds a new column to the grid and a new entry field to the popup form in ASP and PHP.
\r
270 <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
273 <dd>name that appears on the grid column's heading and also on the popup form
\r
276 <dd>string containing a code that controls how the column is displayed on the input form
\r
279 <li><strong>S</strong>:
\r
280 Display this column as a drop-down select list during data entry.
\r
281 Values may be specified using the "SelectValues" or "SelectSql" options.
\r
282 If neither is specified, then the values for the column are obtained using
\r
283 a "select distinct" query.
\r
284 <li><strong>R</strong>: Same as "S", except the items are displayed using radio buttons.
\r
285 <li><strong>SL,RL</strong>:
\r
286 Same as S & R, except that a lookup value is displayed in table view
\r
287 (uses query specified by SelectSql).
\r
288 Typically used on columns that are foreign keys. SQL to get the display value
\r
289 is specified using the "SelectSql" option.
\r
290 <li><strong>CL</strong>: Same as "SL", except that the value is selected
\r
291 using a custom control (such as the Rico Tree control).
\r
292 The SelectCtl option must be assigned the id of the custom control.
\r
293 <li><strong>N</strong>:
\r
294 Same as "S", but allows the user to create a new value.
\r
295 Typically used <em>without</em> the "SelectValues" or "SelectSql" options.
\r
296 <li><strong>H</strong>: column is hidden from the user (DefaultValue will be stored in the table on adds and edits)
\r
297 <li><strong>D</strong>: this is a date field (blanks allowed if column allows nulls)
\r
298 <li><strong>DT</strong>: same as D, except that it also includes the time
\r
299 <li><strong>I</strong>: integer number (blanks allowed if column allows nulls and required is false)
\r
300 <li><strong>F</strong>: floating-point number (blanks allowed if column allows nulls and required is false)
\r
301 <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
302 <li><strong>T</strong>: standard text field (blanks allowed)
\r
303 <li><strong>TA</strong>: text area field
\r
304 <li><strong>tinyMCE</strong>: rich text edit field using the
\r
305 <a href="http://tinymce.moxiecode.com/">tinyMCE</a> library.
\r
309 <dd>column's default value in the form view
\r
312 <p>The equivalent to AddEntryField() in .net is to declare column fields as part of the markup.
\r
313 The "ColData" attribute contains the default value.
\r
314 Here is an example from ex2edit.aspx:
\r
316 <Rico:Column runat='server' heading='Order#' width='60'
\r
317 ColName='OrderID' EntryType='B' ColData='<auto>' />
\r
320 <dt>AddEntryFieldW (ColumnName, Heading, EntryTypeCode, DefaultValue, ColWidth)
\r
321 <dd>Same as AddEntryField except an extra parameter is added for column width (in pixels).
\r
323 <dt>AddCalculatedField (ColumnFormula, Heading)
\r
324 <dd>ColumnFormula is any valid SQL expression or subquery.
\r
325 If the subquery needs to reference a column in the table being displayed,
\r
326 then the column name should be prefaced with the alias "t."
\r
327 Calculated fields will be displayed in table view, but not in form view.
\r
329 <dt>AddFilterField (ColumnName, FilterValue)
\r
330 <dd>Only display records where the contents of ColumnName=FilterValue.
\r
331 This becomes a hidden field (entry type H).
\r
333 <dt><a name='ConfirmDeleteCol'></a>ConfirmDeleteCol (ConfirmDeleteColumn in .net plug-in)
\r
334 <dd>The text content of the column will be included in delete confirmation messages
\r
337 <dd>In table view, sort by this column in ascending order (applies to most recently added field)
\r
340 <dd>In table view, sort by this column in descending order (applies to most recently added field)
\r
345 <h2>FIELD DEFINITION-PROPERTIES</h2>
\r
347 <p>All <a href="LiveGrid.html#column">LiveGrid</a> column properties are supported, in addition to these which are specific to LiveGrid Forms.
\r
352 <dd>When false, the column value will be left unquoted when inserting or updating
\r
353 the database (default=true). This makes it possible to populate columns with
\r
354 SQL function calls. For example:
\r
356 oForm.AddEntryField "LastEditUser","","H","suser_sname()"
\r
357 oForm.CurrentField("AddQuotes")=false
\r
358 oForm.AddEntryField "LastEditDate","","H","getdate()"
\r
359 oForm.CurrentField("AddQuotes")=false
\r
363 <dd>Boolean value that specifies whether the input field may be left empty
\r
364 (default: false if column allows nulls and EntryType is not "B", true otherwise).
\r
367 <dd>Boolean value that when true, specifies that this entry field should placed on the same form row as the last field
\r
368 (default: false - each form field is place on a separate row).
\r
370 <dt><a name='AltTable'></a>AltTable (TabId)
\r
371 <dd>Specifies that the field should be stored in an alternate table
\r
372 TabId should be the value returned by a previous call to <a href='#DefineAltTable'>DefineAltTable</a>
\r
375 <dd>For columns with entry type "TA", this is # of rows to display in the
\r
376 textarea when in form view (default 4)
\r
379 <dd>For columns with entry type "TA", this is # of columns to display in the
\r
380 textarea when in form view (default 80)
\r
383 <dd>If true, then the grid is filtered by the default value for this column (default=false)
\r
386 <dd>Creates a title tag containing the specified text (form view only). So if the user
\r
387 hovers over the field label, they will see this text as balloon help. For example:
\r
389 oForm.CurrentField("Help")="Date must be entered in mm/dd/yyyy format"
\r
393 <dd>A string containing a regular expression. User entries will be checked to ensure
\r
394 they match the pattern specified. There are a few special values:
\r
396 <li>"email" - tests for a valid email address
\r
397 <li>"float-unsigned" - tests for a valid unsigned floating point (real) number
\r
398 <li>"float-signed" - tests for a valid signed floating point (real) number (this is the default when EntryType is "F")
\r
399 <li>"int-unsigned" - tests for a valid unsigned integer number
\r
400 <li>"int-signed" - tests for a valid signed integer number (this is the default when EntryType is "I")
\r
402 <br>It is recommended that a Help entry be included
\r
403 whenever a pattern is specified. If the field fails validation, the help text
\r
404 will be included in the error message presented to the user. For example:
\r
406 oForm.CurrentField("Help")="Enter date as mm/dd/yyyy"
\r
407 oForm.CurrentField("pattern")="^\\d{1,2}/\\d{1,2}/\\d{4}$"
\r
411 <dd>Specifies the minimum/maximum allowable values for fields with EntryType "I", "F", and "D".
\r
414 oForm.AddEntryField "field1", "Field #1", "I", "0"
\r
415 oForm.CurrentField("min")=1
\r
416 oForm.CurrentField("max")=10
\r
417 oForm.CurrentField("Help")="Enter a value between 1 and 10"
\r
419 oForm.AddEntryField "field2", "Field #2", "D", Date()
\r
420 oForm.CurrentField("min")="2000-01-01"
\r
421 oForm.CurrentField("max")="2099-12-31"
\r
422 oForm.CurrentField("Help")="Enter a value in the 21st century!"
\r
426 <dd>Only write this field to the database when peforming an insert (default=false).
\r
428 oForm.AddEntryField "CreateDate","","H","getdate()"
\r
429 oForm.CurrentField("AddQuotes")=false
\r
430 oForm.CurrentField("InsertOnly")=true
\r
434 <dd>Only write this field to the database when peforming an update (default=false).
\r
436 oForm.CurrentField("UpdateOnly")=true
\r
440 <dd>If true, data is displayed on the entry form but cannot be changed, text is gray (default=false).
\r
441 Does not apply to entry types of S, SL, N, R, RL -- use objTE.CurrentField("FormView")="hidden" instead.
\r
444 <dd>Specifies the choices the user sees in form view for EntryTypes of N, S, and R.
\r
445 If supplied, then this should be a string of comma-separated values. For example:
\r
447 oForm.CurrentField("SelectValues")="Y,N"
\r
451 <dd>Specifies the SQL select statement to use for EntryTypes of SL, CL, and RL.
\r
452 The select statement should return 2 columns: the first being the code
\r
453 and the second being the text value/description. For example:
\r
455 oForm.CurrentField("SelectSql")="select ID,Name from Customers"
\r
459 <dd>SelectSql serves 2 purposes. First, it is used to retrieve the appropriate
\r
460 data to display in the grid. Second, it is used to populate the values in
\r
461 the select box (SL) or radio buttons (RL) on the pop-up form. In some cases,
\r
462 you may want these to be different. In the SelectSql example above, we
\r
463 are retrieving customer name. But let's say that our Customers table has
\r
464 a "CreditHold" field and we want to disable the selection of customers on
\r
465 credit hold in the form view, but still display them in the grid.
\r
466 This is where SelectFilter comes in:
\r
468 oForm.CurrentField("SelectFilter")="CreditHold='NO'"
\r