Forms

Create an interactive form in /forms. This form is then placed with the Form Placeholder and can collect data/payment from a webuser through a page.

Example: /playground/form

Recommendation: It is a good idea to place your form on a page in such a way that the form is OBVIOUS – as some users and observers have complained about forms that are not obvious when a page is loaded.

If an administrator is entering CC transactions, in the absence of an email address, enter none@none.com

The forms manager at /forms allows a user with sufficient rights to create and edit forms for their web service.

Form Name	must be well formed (no weird SQL syntax), spaces are replaced with _. Name must be preceded with _Name so we can use any name we want (helps protect the SQL)
Form locking rules	not implemented in this version
Form edit rules	not implemented in this version
Form Title	optional. Appears a the HTML table title on render
Form WebServiceID	assign this table to a given service/department/ministry
Form CreditcardProcessingField	optional. In the form _element_Name. IF exists, Form will collect a credit card transaction and bill the amount from that field. It’s recommend that that element be locked, and calculated if needed.
CreditCard Gateway	Choose from configured gateways to process a CC transaction
Form GLIDCode	required if CreditcardProcessingField exists. Obtained from treasury to tie the transaction into the accounting system.
Form CopyReceiptEmails	optional. Comma separated list of email@addresses.com in ADDITION to the current webuser you wish to receive a copy of the form when a webuser fills it out
Form EmailReceipt	If checked (T or Y value) then the webuser will receive a copy of the submitted form via email. In the case of a form processing a CC transaction, this is controlled by the _Transaction table EmailReceipt value.
Form CustomReceipt	IF not blank, this prepends the receipt (both drawn in the response and emailed). IF the form is not a _transaction form - this REPLACES the default message that the form can be filled out again.
RenderStyle	where the form draws validation msgs.

0. Elements are the fields of the form.

1. Element # is the order number it is to appear in the form. This column is sorted ascending. Use whole integers, like 1, 2, 3, etc.

2. The Element names should be unique, and begin with an underscore character (_), like _Name.

3. Default Value is optional. This can be static, or dynamic. Dynamic values in the format [$User_profile_attribute_name] include:

[$User_First_Name]
[$User_Last_Name]
[$User_Name]
[$User_Email]
[$User_Address]
[$User_City]
[$User_State]
[$User_Zip]
[$User_Phone]

4. Element Type is the HTML control drawn on the client.

Presentation Types
Element Type	Description
CAPTCHA	/ITS/CMSCAPTCHA (used in conjunction with CAPTCHA validation rule)
Checkbox	Value = DefaultValue cannot be set to checked by default (currently).
DropDownList	processes List. Displays as a dropdown list box
Hidden	Does not show on the form. Does show on the receipt.
RadioList	processes List. Displays as a list of radio buttons.
TextArea	HTML Text Area
TextArea_Big	Larger HTML Text Area
TextBox	Textbox. Single Line.
TextBox_Locked	Textbox. Single Line. Locked.

5. DataType is chosen when the element is added, and corresponds to the value held in the server. IF you are hoping to do calculations on the data, choose Number.

6. Help/Show More is optional, and draws behind a [?] link on the form to further describe the field. Click [+/-] to toggle element extended attributes.

7. List corresponds to the DropDownList and RadioList Types. Lists should have more then once choice (otherwise use a CheckBox control). The List Name attribute is what shows on the screen, and the List's value attribute is what is stored in the database if that name is chosen in the list. Therefore, Values should be unique if you want to determine what was selected from the list.

8. A Validation Rule is a method to ensure you get the data you're soliciting. This includes whether it's required or needs to be of a certain type or in a certain format. LenthBetween(x,y) requires components (the minimum number of characters, the maximum number of characters) and the rest of the rules do not require components. CAPTCHA is detailed here. The msg is displayed if the rule is not satisfied. More then one rule can be added to each Element, therefore if more then one rule is not met the first msg is displayed for a rule that was not satisfied. Fields should have a minimum of LengthBetween(x,y) and set components to 0,500 and msg to 'please enter fewer then 500 characters for fieldname' to ensure we can store data people give us.

Validation Rules:
Validation Rule	Functionality
CAPTCHA	Enter characters from the returned graphic correctly. Helps ensure only people have access to form and form is not auto-filled out by a computer. (Used in conjunction with presentation type CAPTCHA)
isCAN_CI_number	Enter a valid Canadian Insurance Number like 999999999
isCANPostalCode	Enter a valid Canadian Postal Code Z5Z-5Z5 or Z5Z5Z5
isDate	Enter a valid Date like 12/02/1980 in MM/DD/YYYY format
isEmail	Enter a valid email like email@host.com
isMoney	Enter a valid money amount like 10.00 $10.00, -10, 10.001, A10, and BLANK are all invalid.
isNumber	Enter a valid number like 10 or -100.251 the word 'TEN' is invalid.
isPhoneNumber	Enter a phone number (123) 123-1234
isUS_SS_Number	Enter a valid US Postal Code like 12345 or 12345-1234
isUSPostalCode	Enter a valid US Postal Code like 12345 or 12345-1234
LengthBetween	Components required XX,YY , like: 1,10 This would ensure the length of the received field was between 1 and 10 characters. Current text fields can hold up to 500 characters. XX and YY in the Validation Message are replaced with the appropriate values, so message "Enter text between XX and YY characters long" would be displayed as 'Enter text between 1 and 10 characters long'

9. Calculated Field is most often used when receiving payment. Each Field should be a number, and not blank, otherwise it's skipped in the calculation. It is recommended that you put a calculated field in a locked control (like textbox_locked) or hidden so as not to confuse the end user.

Calculated fields:

Fields are processed FIRST and THEN validation occurs.
Fields processed before the current calculated field are available automatically as their calculated field sum (post processing); Elements that have not been processed yet are available as their CURRENT value (pre processing)
fields are optional. They are used to either COPY the value of another control, or CALCULATE
fields calculated form left to right regardless of operator. operators supported + - * /
fields do not support negative numbers in the form 1+-1, but will correctly solve 1-2-3
field can lookup from other element names like [_cost] * 0.5 where cost is a control name in the current form
field can lookup from the parent form such as in the relationship between a form and it's payment form. such that [!elementname] looks up the forms value. Initially used in CC payments to ensure that the amount cannot be tampered with from the originally calculated value but supports all parent form keys including reserved ones. Reserved key/values: [!submittedformname] and [!parentformamount] element names
field can lookup variables from a user profile [$User_x] like User_Zip
field Examples: 1*2-3/2 or [$User_Zip] + 1 or [cost element name] + 10.00
field SKIP anything that is NOT a number or decimal number, example 1 + 2 -a = 3
field ignores spaces when calculated, therefore 1+2+3 is the same as 1 + 2 + 3

10. You can add elements, but you cannot remove them to protect you from removing submitted values. IF you wish a field to be 'removed', set it's Type to Hidden.

To Add a form to a page, add the Form placeholder from the directory.

Double-click the form placeholder icon (flag) and set the custom attribute formname to the name of your form.

If the form is receiving money (Credit card transactions) it is recommended to configure the form to email the customer a receipt, and put the form in a security wrapper only allowing authenticated users access to the form - ensuring we know who we're doing business with. IF a webuser is not logged in, the transaction stores the UID=0

This image demonstrates what a rendered form may look like.