ION_FORM

The ION_FORM tag pair defines a form in an ION Script page. An ION Script form is similar to an HTML form, except that the action taken when an event occurs inside the form is not limited to one choice. Instead, the source of the event determines what action is taken. For example, a form can contain multiple ION_BUTTON elements. Each button can be assigned a different EVENT that occurs when the button is clicked. Only data values within a form and variables marked as persistent are passed on to the next ION Script page.

Syntax

<ION_FORM
[METHOD={"GET" | "POST"}]
[NAME="name"]
[TARGET="frame target"]
[<FORM> attributes except ACTION] >

Attributes

METHOD

GET — Passes information via the URL. The amount of information that can be passed using the GET method is limited by server and browser URL length limitations. An advantage of the GET method, however, is that the user can bookmark the URL, and the browser's "Reload" button works seamlessly. This is the default method.

POST — Form input is submitted as an HTTP POST request. POST does not impose the length restrictions imposed by GET. Therefore, the POST method can be used to submit forms containing amounts of data that would be too large to submit in a URL using the GET method. A disadvantage of the POST method is that the resulting page cannot be bookmarked, and if the user clicks the browser's "Reload" button, a "Repost form data?" dialog will appear.

NAME

The name of the form. This name can be used to access form elements and methods through JavaScript/VBScript. For example, you could use JavaScript to perform client-side validation of form data before allowing the form to be submitted to the server, thereby saving your server from having to check form data. This attribute can contain a variable.

TARGET

The name of the window or frame in which to load the URL specified by an EVENT contained within the form when the form is submitted. This attribute can be set to either the NAME attribute of an HTML <FRAME> or <IFRAME> tag, or to one of four predefined windows: _blank, _parent, _self, or _top. See Targeting Different Frames for a description of these predefined windows. See Overview of Fixed Framesets for an example of how to use the TARGET attribute.

ONSUBMIT

The script to execute when the form is submitted. See Using JavaScript and VBScript for information on specifying this attribute.

ONRESET

The script to execute when the form is reset. See Using JavaScript and VBScript for information on specifying this attribute.

Forms Containing a Single Text Field

HTML forms that contain a single text field can be submitted by pressing the Enter key when the cursor is in the text field. If your ION_FORM contains a single text field, pressing the Enter key when the cursor is in the text field will cause an error unless an event is associated with the text field. To prevent an error, make sure you have defined an event with the same name as the NAME attribute of the text field. For example, the form on the following ION Script page can be submitted with the button or the Enter key:

<ION_SCRIPT>  
<ION_HEADER>  
   <EVENTS>  
      <EVENT_DECL NAME="BUTTON_PRESS" ACTION="ion://page2.ion"/>  
      <EVENT_DECL NAME="TEXT_ENTERED" ACTION="ion://page2.ion"/>  
   </EVENTS>  
</ION_HEADER>  
<ION_BODY>  
   <ION_FORM>  
      This form can be submitted by clicking the button or <BR>  
      pressing the Enter key while the cursor is in the <BR>  
      text field.<BR><BR>  
      <INPUT NAME="TEXT_ENTERED" TYPE="TEXT" VALUE="5">  
      <ION_BUTTON EVENT="BUTTON_PRESS" TYPE="BUTTON"/>  
   </ION_FORM>  
</ION_BODY>  
</ION_SCRIPT>

<ION_SCRIPT>  
<ION_BODY>  
   You submitted <ION_VARIABLE NAME="$Form.TEXT_ENTERED"/>  
</ION_BODY>  
</ION_SCRIPT>

Note that the ION_BUTTON uses an event with a different name than the event associated with the text field, but the ACTION is the same. This avoids submitting two parameters with the same name.

HTML Mapping

The ION_FORM tag is converted to the HTML <FORM> tag. The value of the ION Script Parser URL, which is specified in the ION Script Configuration utility or the .ionsrc file, is used as the value of the <FORM> tag's ACTION attribute, and the METHOD attribute of the <FORM> tag is set to "GET". For example, if you have set the ION Script Parser URL to "http://myhost.mydomain.com/cgi-bin/ion-p", then <ION_FORM> is converted to the following HTML:

<FORM ACTION="http://myhost.mydomain.com/cgi-bin/ion-p"  
   METHOD="GET">

All attributes of the HTML <FORM> tag can be used in the ION_FORM tag. Note that the attributes listed above (ACTION, METHOD, etc.) are simply attributes of the <FORM> tag, and are listed here for convenience.