The <form> element occurs within the body element but is included here to define how this element can be used with Web Companion to make HTTP requests. In section 5.2, "XML Request Commands for Web Companion," all of the requests were made with direct commands in the browser. In section 6.34, "Hyperlinks and Anchors," the anchor or hyperlink is used to send the request. The <form> children elements are <input>, <textarea>, <button>, <select>, and <option>.
The main attributes of <form> are action and method. The action attribute is the URL to the CGI, in this case Web Companion, and is required to have a value. The value for the Web Companion action is the root path to the Web folder. When the value of the action attribute is specified as "fmpro", "FMPRO", or "Fmpro", Web Companion can process the request. The action can also be a JavaScript call. The method attribute can be "get" or "post", with "get" as the default if no method is specified.
<form action="fmpro" method="post" target="_top"> <!-- other form elements here --> </form>
If you use a <form> with <table> elements, the <form> elements must be around the <table> elements or entirely within a cell. You must not intersperse the form elements <input>, <select>, <text- area>, or <button> between table rows or cells (<tr> and <td>).
Another attribute for the <form> element is enctype. The value of this is the ContentType of the document being submitted. The default value is "application/x-www-form-urlencoded" if you do not specify an enctype. This attribute can be used with the <input type="file"> to upload attachments with the form submitted. The Web Companion is not designed to allow file uploads. Files can be uploaded with File Transfer Protocol (FTP) and a field submitted with the path to the file. Your action must be to another CGI or application server.
<form action="cgiCall" method="post" enctype="multipart/form-data"> <input type="file"> </form>
The other attributes for the <form> element are target, accept, accept-charset, name, id, class, lang, dir, style, title, onsubmit, onreset, onclick, ondblclick, onmousedown, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, and onkeyup.
The most common <form> element for entering text is the <input> element. The <input> element has the type attribute to specify the element details. These types can be text for standard field entry and password for standard text entry with an asterisk to hide the entry.
The type="password" setting does not encrypt the entry; it only replaces every character with an asterisk, and the transmission of the entry is not secure. These two input types have a name attribute to specify where the data is to be stored. The value attribute is where the actual entry is made. If the value is not empty, typing over the contents can change it when the form is submitted. The size attribute is the number of characters to be displayed in the INPUT element. The maxlength attribute limits the number of characters that can be entered into the <input> field. The <input> element is always empty, as seen in the examples below:
<input type="text" name="firstName" value="Joe" size="30" /> <input type="text" name="state" value="" size="5" maxlength="2" /> <input type="password" name="userPass" value="Login here" size="20" />
Other <input> types are "checkbox" and "radio". These two <input> types are similar to the value list formats found in FileMaker Pro. The FileMaker Pro Help topic "Formatting fields to use a value list" can help you understand these two types of text formats in FileMaker Pro and in the browser. The check box allows more than one selection to be entered into the same field and is often rendered as a small square in the browser. The radio button is mutually exclusive; selecting one will deselect the other values for the same field. The radio button type may render as a small circle in the browser. Examples of these two <input> types are shown in Listing 6.30. You must specify a label for each element or the user will not know what is being checked. The checked attribute makes the default selection(s) for these elements.
<!-- any or all of these values may be selected --> <input type="checkbox" name="choices" value="1" /> One<br /> <input type="checkbox" name="choices" value="2" checked="checked" /> Two<br /> <input type="checkbox" name="choices" value="3" /> Three<br /> <input type="checkbox" name="choices" value="4" checked="checked" /> Four<br /> <!-- only one of these values may be selected --> <input type="radio" name="choices" value="1" checked="checked" /> One<br /> <input type="radio" name="choices" value="2" /> Two<br /> <input type="radio" name="choices" value="3" /> Three<br /> <input type="radio" name="choices" value="4" /> Four<br />
Multiline text is entered with the <textarea> element. This element has the attributes rows and cols to specify the visible number of lines of text (rows) and the number of characters (cols) for the width of the text area. This element is never empty and has the start and end tags. The <textarea> element does not use the value attribute to display the default content of the field. The text between the two tags is the actual content of the <textarea>.
<textarea rows="3" cols="40">This text will be displayed in a TEXTAREA box.</textarea>
By default, a scroll bar is rendered for this type of text input field in the browser. Other attributes for the <textarea> element are name, id, class, lang, dir, title, style, readonly, disabled, tabindex, onfocus, onblur, onselect, onchange, onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, and onkeyup.
The <select> element allows the user to choose values in a pop-up menu or drop-down list. Specifying the attribute size renders the menu or list. If the size attribute has a value of more than 1, the list is rendered; otherwise the menu is rendered. More than one value can be selected in the list if the attribute multiple is set. The <select> element is never empty and contains the <option> element to display the choices. The attribute name specifies the field that will be populated by the value of the option selected.
The <option> element has the attribute value, which contains the value of the <select> element when the option is chosen. The <option> element may be empty but must contain the attribute label if the displayed text is to be different from the text of the value. The <option> tag may have a start and end tag with the text of the label between them. To display the text of any value by default, the attribute selected is set in the OPTION element.
Other attributes for the <select> and <option> elements are name, id, class, lang, dir, title, style, readonly, disabled, tabindex, onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, and onkeyup. Examples of the <select> and <option> elements are shown in Listing 6.31.
<select name="color"> <option value="Blue" /> <option value="Red" selected="selected" /> <option value="Green" /> <option value="P" label="Purple" /> </select><br /> Choose your sizes: <select name="sizes" size="5"> <option value="S">Small</option> <option value="M">Medium</option> <option value="L">Large</option> <option value="XL">Xtra Large</option> </select>
The INPUT element can be used to pass along hidden text when the form is submitted. Many times this is the name of the database (-db), the name of the layout (-lay), the format (-fmp_xml), and anything else you want to pass. The <input> element has the type attribute, which has a value of "hidden". This hides the name and value from being seen if the form is submitted with the "post" method. Examples of the hidden input element are shown in Listing 6.32.
The contents for an INPUT type="hidden" can be seen in the source code for the HTML document. This form element is not secure.
<input type="hidden" name="-db" value="myDatabase.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> <input type="hidden" name="-recid" value="12345" /> <input type="hidden" name="userName" value="Beverly Voth" />
The hidden input type can also be used to force an "empty" value when submitting data to Web Companion. This value is necessary for value list fields. Sometimes clearing all the values from check boxes, for example, does not clear them in the database when the form is submitted. Use the same name as the values list in the hidden input. An example of this usage is seen here:
I would like more information about: <br /> <input type="hidden" name="product" value="" /> <input type="checkbox" name="product" value="FMP" /> FileMaker Pro<br /> <input type="checkbox" name="product" value="FMD" /> FileMaker Developer<br /> <input type="checkbox" name="product" value="FMS" /> FileMaker Server<br /> <input type="checkbox" name="product" value="FMU" /> FileMaker Unlimited<br /> <input type="checkbox" name="product" value="FMM" /> FileMaker Mobile<br />
If the action is repeated with a hidden empty value, the form can be submitted when the user presses Return or Enter from the keyboard, instead of clicking the submit button with the mouse.
<input type="hidden" name="-find" value="" /> <input type="submit" name="-find" value=" FIND " />
The form must be submitted to CGI for processing. Until the user clicks the submit button or presses Return or Enter, the information just sits in the fields on the web page with the form. The INPUT element can have a type attribute with the value "submit". This tells the browser to send the data in the fields to the action value of the FORM element. The possible values for the name attribute of the submit input are seen in Listing 6.33. The value attribute is the text that will be displayed in the button when it is rendered in the browser.
<!-- CREATE A NEW RECORD --> <input type="hidden" name="-new" value="" /> <input type="submit" name="-new" value=" ADD " /> <!-- EDIT A RECORD --> <input type="hidden" name="-edit" value="" /> <input type="submit" name="-edit" value="Update" /> <!-- DELETE A RECORD --> <input type="hidden" name="-delete" value="" /> <input type="submit" name="-delete" value="Delete!" /> <!-- FIND A RECORD --> <input type="hidden" name="-find" value="" /> <input type="submit" name="-find" value=" BEGIN SEARCH " /> <!-- FIND ALL RECORDS --> <input type="hidden" name="-findall" value="" /> <input type="submit" name="-findall" value="Show All Records" />
To clear the fields or reset to predefined values on the form, use the INPUT type attribute value of reset:
<input type="reset" name="reset" value="Clear the fields" />
A FORM may also be submitted by including a BUTTON element instead of the INPUT type. This method has more options than input type="submit" because an image can be used along with content. The attribute type can be one of three values: submit (default if no type is specified), reset, and button. The name attribute functions the same as the submit input. The value attribute is not used to label the button, but the content is used. This element is never empty and must contain an image or text:
<button type="submit" name="-find" value="">FIND <img src="findbutton.gif" border="0" /></button>
Image maps may not be used with the BUTTON element. The BUTTON element must not contain the other FORM elements.
The last value for the type attribute for the <button> element will perform any client-side script that is a part of the button. It is not used to submit a form. The attributes for the event calls are listed in the "Attributes for Script Calls" section earlier in this chapter. If the script is JavaScript, it must be declared on the same page as the BUTTON or referenced with the <link> element in the <head> element.
<button type="button" name="showMe" value="showMe" onclick= "doThisScript">SHOW ME!</button>
Other attributes for the <button> element are disabled, tabindex, accesskey, onfocus, onblur, id, class, title, lang, dir, style, onclick, ondblclick, onmousedown, onmouseover, onmousemove, and onmouseout.
You can read more about HTML elements in "HTML 4.01 Specification," http://www.w3.org/TR/html401, and "1.0: The Extensible Hypertext Markup Language XHTML," found at http://www.w3.org/TR/xhtml1.
The CGI requests in section 5.2, "XML Request Commands for Web Companion," were all made with the hyperlinks or direct inclusion in the browser address bar. Another method of sending information to Web Companion from a browser is the <form> element and associated elements. The attributes for the <form> element are method and action. Use the value "post" for the method in most cases. The action value is to Web Companion itself: "fmpro". If you are using a <frameset>, you can include the <form> attribute target with the value of the named window or frame. The following example is a basic <form> with hidden fields for some of the request values and is equivalent to the hyperlink "fmpro?-db=Xtests.fp5&-lay=web&- findall."
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtexts.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="submit" name="-findall" value="Find All" /> </Form>
The other actions and XML commands will be covered shortly, but first we will discuss the fields in your database. The <input> element is most often used for adding data to your fields. The name attribute is the name of your field. This field must be on the layout or you will receive the error, "102 Field is missing." An advantage of using the <form> and <input> elements, instead of the hyperlink, is that field names (the value of the name attribute) are enclosed in quotes and field names with spaces can be used. Examples of the <input> element are listed below. The <input type="text"> is the standard method of passing data to a CGI. The type of field such as number, date, and time are also "text" in the browser but are entered correctly when passed to your FileMaker Pro database.
<input type="text" name="First Name" value="" size="30" /> <input type="text" name="zipcode" value="" size="10" maxlength="10" /> <input type="text" name="age" value="" size="5" /> <input type="text" name="OrderDate" value="" size="20" />
The check boxes, radio buttons, select pop-up lists, and menus can be used with the fields on your layout. The name attribute is the name of your field. These are shown in the following examples. Multiple input statements will be used with the same field name for check boxes and radio buttons.
<!-- checkboxes: the field in the database is "colors" --> Choose your colors:<br /> <input type="checkbox" name="colors" value="blue" /> Blue<br /> <input type="checkbox" name="colors" value="red" /> Red<br /> <input type="checkbox" name="colors" value="green" /> Green<br /> Choose your colors: _ Blue _ Red _ Green <!-- radio buttons: the field in the database is "fish" --> Do you like to fish? <input type="radio" name="fish" value="yes" /> Yes <input type="radio" name="fish" value="no" checked="checked" /> No<br /> Do you like to fish? () Yes () No <!-- select menu: the field in the database is "state" --> <select name="state"> <option value="" selected>- State -</option> <option value="AL">Alabama</option> <option value="AK">Alaska</option> ... <option value="WA">Washington</option> </select>
Value list items may not clear if you uncheck or unselect all of the val- ues. Add a hidden empty input to submit a clear command to the field. Use the same name as the field.
<input type="hidden" name="colors" value="" /> <input type="checkbox" name="colors" value="blue" />Blue
Text areas can also be used for input. If the field has contents, it is displayed between the start and end tags. For new data entry, remember to leave no content between the tags. If a return is inserted between the start and end tags for the <textarea> element, it may be interpreted as a space when the form is displayed in the browser or submitted for processing. You may have a space in the field in a search request, for example, and get unexpected results.
<textarea name="scrollableField" rows="10" cols="150"></textarea>
The <form> is generally submitted to the database with the submit button. This <input> element is where you place your action, such as find, edit, or delete. Include a hidden empty value for the same action to allow the browser to submit when the user presses the Enter key instead of clicking the button. The label for the button is taken from the value attribute. Example actions used to submit the forms are shown in the listings below. These are equivalent to the hyperlink actions in Chapter 2 and the results will be the same.
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> First Name: <input type="text" name="firstname" value="Joe" /><br /> Last Name: <input type="text" name="lastname" value="Brown" /><br /> <input type="hidden" name="-new" value="" /> <input type="submit" name="-new" value="New Record" /> </Form>
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> <input type="hidden" name="-recid" value="1234" /> <input type="hidden" name="-dup" value="" /> <input type="submit" name="-dup" value="Duplicate Record" /> </form>
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> <input type="hidden" name="-recid" value="36488" /> First Name: <input type="text" name="firstname" value="Jane" /><br /> Last Name: <input type="text" name="lastname" value="Doe" /><br /> <input type="hidden" name="-edit" value="" /> <input type="submit" name="-edit" value="Update Record" /> </form>
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> <input type="hidden" name="-recid" value="36488" /> <input type="hidden" name="-delete" value="" /> <input type="submit" name="-delete" value="Delete Record" /> </form>
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-dso_xml" /> First Name: <input type="text" name="firstname" value="Joe" /> <input type="hidden" name="-lop" value="and" /> <br /> Last Name: <input type="text" name="lastname" value="Brown" /> <br /> <input type="hidden" name="-find" value="" /> <input type="submit" name="-find" value="Find Records" /> </Form>
<!-- find only this record --> <input type="text" name="-recid" value="36488" /> <br /> <input type="hidden" name="-find" value="" /> <input type="submit" name="-find" value="Find Record" /> </form> <!-- find any record --> <input type="hidden" name="-findany" value="" /> <input type="submit" name="-findany" value="Random" /> </form> <!-- find all records --> <input type="hidden" name="-findall" value="" /> <input type="submit" name="-findall" value="All Records" /> </form>
<form method="post" action="fmpro"> <input type="hidden" name="-db" value="Xtests.fp5" /> <input type="hidden" name="-lay" value="web" /> <input type="hidden" name="-format" value="-fmp_xml" /> <input type="hidden" name="-view" value="" /> <input type="submit" name="-view" value="Layout Info" /> </form>
The action requests for database names (-dbnames), layout names (-layoutnames), script names (-scriptnames), open database (-dbopen), and close database (-dbclose) follow the same format. Use the hidden field with the same name to allow browsers to submit upon pressing the Enter key.
The parameters, like database (-db) and layout (-lay), can be hidden fields or can be input types to allow the user a choice. If you will be processing the results with a stylesheet, do not make the format (-format) a choice. The other parameters, such as operator (-op) or logical operator (-lop), more commonly may be user choices when performing a find.
The -recid parameter is required with -edit, -dup, and -delete actions and is optional with the -find action. The value of the -recid parameter will be returned in the XML result with all actions that return records. The user will rarely see this value, so it will be submitted as a hidden <input> element:
<input type="hidden" name="-recid" value="123456" />
The -modid (record modification count) is also returned with these records, but it is automatically set by FileMaker Pro. The -modid should not be set with a hyperlink or <form> <input> method.
Stylesheets may be specified by the user or set as hidden fields:
<input type="hidden" name="styletype" value="text/xsl" /> <input type="hidden" name="stylehref" value="Xtests.xsl" />
Logical operators may be hidden or input. To allow only specified values, use radio buttons or a pop-up menu. The logical operator (-lop) is placed between fields to specify the kind of find.
First Name: <input type="text" name="firstname" value="Joe" /> <select name="-lop"> <option value="and" selected="selected">AND</option> <option value="or">OR<option> </select> <br /> Last Name: <input type="text" name="lastname" value="Brown" /> <br />
Comparison operators are often presented in a selection pop-up, too. Listing 5.22 shows an example of this selection type.
Your users may want to choose the number of records returned. The -max parameter can be an <input> element or <select>. The example showing this is in Listing 5.25.
Sorting can be by particular fields and sort order. Often this is by user choice. The following code shows these choices in the <form> elements <select> and <input type="radio">.
Sort by: <select name="-sortfield"> <option value="firstname">First Name</option> <option value="lastname" selected="selected">Last Name</option> <option value="company">Company</option> <option value="invoiceNum">Invoice Number</option> <option value="invoiceDate">Invoice Date</option> </select> <input type="radio" name="-sortorder" value="ascend" /> Ascending <input type="radio" name="-sortorder" value="descend" /> Descending<br />
Scripts are rarely a user choice but may be specified by the <input> element in a <form>.
<input type="hidden" name="-script" value="emailMe" />
The FORM elements are used to submit data and action commands to a FileMaker Pro database. The result returned depends upon the input submit name (the XML action command). If a -new, -delete, or -edit action is used, the single record is returned. If a -find, -findany, or -findall action is used, the result is the found set of records. A stylesheet may be called to display the XML results by using a hidden type INPUT element.