DOCUMENTATION ON HTML <FORMS>: [A]

A) DOCforms contains basic HTML doc on <Form>s;
	plus it is about client-side manipulation of forms, mainly to send
	queries to other servers from me.
   It is also about my php support for serverside forms: using php to
   process incoming queries, and using forms to elicit that input from users.

B) DOCformsJAVA contains stuff on how to use java with forms.
========== ========== ========== ==========

*A small introduction is near the end (in sec.5) of  ~steve/demo.html
*This is the main holder for doc. on forms.
*demoforms.php is the big demo of my PHP enhanced use of forms.

Jump down this page to find:
	A) Philosophy / basic underlying approach
	B) doc. on std HTML/browser instantiation of them.
	C) my php toolkit for forms. 
========== ========== ========== ==========
A] Philosophy / basic underlying approach
----- ----- ----- ----- -----

Forms seem to have basic facilities you might want to use, not necessarily for
forms, for:
*User input, and transfer to a server side script or program.
*HTML appearances: buttons, menus, boxes for scrolled output, and input
*A different web access method POST.
*Hence, a way of transferring variable settings from (hidden) HTML settings
to the server script/software

Thus you can consider mixing them with the other standard mechanisms:
<LI>Use of "url?var1=value1&amp;var2=value2" to send variable settings by URL.
However this only works if the server software has explict code to parse these.
<LI>Use of standard links within forms for the appearance.  This can be done
by using the form attribute ACTION to set a URL to jump to a page, and the
link HREF to call the java routine e.g.
"javascript:document.evaluation.submit();" class="normaddr"
<P>

Forms have items; any item (displayed or not) that has both a name and a
value, will have that encoded and sent as:
url?name=val1&name2=val2&name3=val3+word3b....
Buttons (type "submit") will also have their value sent iff they have both
name and value defined.  (Their value is the button label, so you may see
buttons with value but no name.)

================
Preserving state

Beyond the simple cases, the big issue is how to preserve state in a
multi-step interaction.  Alternative methods are:
a) 	<INPUT type=hidden .>
b)	Cookies
c)	Designing the forms to resubmit every time values estabished in earlier
	iterative interactions with the form. 
	Script demoforms.php illustrates some of this.
d)	Java, setting less obvious attributes of DOM items.

To preserve state in a multi-step interaction, the server/author may put out
pages with hidden variables set to values gathered from the user earlier
(e.g. by a related page ...), so they are re-sent by the form. 

Cookies are an alternative.   Their contents are mainly name=value pairs.
Main use: maintaining state, preventing repetitive logins, shopping baskets
etc.  But also used for logging users' access to a site across time.

If you have multiple forms on one page, then each user submit might be to a
diff. form; and maintaining hidden vars could preserve the state of one form
when the other form submits.


========== ========== ========== ==========
B] DOC. ON STD. HTML/BROWSER INSTANTIATION OF FORMs.
----- ----- ----- ----- -----

FORMs' basic HTML behaviour
Returns a value for the var. associated with every element on the form, except:
	Buttons: only at most the one clicked.
	RadioBtns: at most the one selected [is possible to have none selected]
	Checkboxes: only if checked on.
So state is maintained by being repeated on every FORM invocation;
and type=hidden-s can return extra var-value pairs.

Adding an HTML field corresponding to a pre-existing java
field CAN set the field in the Java DOM object. 
	E.g setting in <input  accessKey=34  disabled=1 ...> 
Note that this is esp. useful for CSS which often corresponds to fields in the
java object.

Nested forms seem to be merged: submitting either returns all the elements
from both.
==========
FORMs' TYPES SYNTAX:  the std. elements ("types") provided in HTML

<FIELDSET> ..</FIELDSET> inside (or outside?) a form, draws a box.
<FIELDSET style='display: inline;'> draws it only big enough, not to RHmargin

Should add a bit here on FORM input of files for upload.


<FORM qname="gbox1" method=GET action=http://www.google.co.uk/search
	target='new'>
<input type=RADIO name=var1 value="reap.ac.uk" qCHECKED >
<input type=CHECKBOX name=var1 value="reap.ac.uk" qCHECKED >
<input type=HIDDEN name=var1 value="val1"> 
<input type=SUBMIT qname=var1 value="Button Label Text"> // BUTTON
<BUTTON name=var1 value=3 qtype=SUBMIT >
	//spec type inside a FORM because default unknown: button,reset,submit 
	Button label text, or IMGs
	</BUTTON>
	This gives a) more freedom with label text;
		   b) disconnect label and returned value
<input type=TEXT name=var1 value="default val" size=21 maxlength=255>
<TEXTAREA name="var9" rows=4 cols=40 >
	 John Smith, you are a cat and a pig 
</TEXTAREA>
<SELECT name="var1" >
	<OPTION value="Aa"  qSELECTED >label/descrip.</OPTION>
</SELECT>

==========

FORMs' TYPES descrip:  the std. elements ("types") provided in HTML
	<FORM name="gbox1" method=GET action=http://www.google.co.uk/search
		target='new'>
Checkboxes:  On/off: return value for var, or nothing.
Checkboxes:  return 0-N multiple values for a single var;
	if you give same var name to multiple checkboxes.
["Multiple": menu, always open, allows multiple return values to one var.]
Radio btns: return 1 of N values for one var. (effectively an always open menu).
	<input type=radio name=sitesearch value="reap.ac.uk" CHECKED >
Menu: 	Ditto. (popup scrolling menu).
Buttons: only returns something if clicked.
	 <INPUT type=submit qname=sa VALUE="search selected site"> 
	 OR? <INPUT type=button qname=sa VALUE="search selected site"> 
Hidden: return a fixed var=value pair.
	Useful for separate web pages all calling a single script processor:
		hidden vars store the state about the one page.
x.checked: java bool var for reading/setting cur. value
x.defaultChecked: whether checked by default
	These 2 apply to radio and checkbox;
	and to <option> (within a menu) but called 'selected' not 'checked'

Textboxes: return a (OE) string.
	 <INPUT TYPE=text name=q size=21 maxlength=255 value="Some text">
	(Both 1-line "TEXT" and multi-line "TEXTAREA".)
	TEXTAREA:
		Its contents are BOTH (concat?) the text put into the HTML
		between open/close <Textarea> tags; AND the contents of the
		var. (Don't indent the text in html!)

		Can spec. box size either in html or CSS:
<TEXTAREA ID='datatext' wrap='off' NAME="<?=$varname?>"
        style='height: 20%;  width: 90%' qROWS=5  qCOLS=40 >
<?=${$varname}?>
</TEXTAREA>
==========

RULES ON HOW BROWSER CONSTRUCTS THE ARG-QUERY-STRING
It overwrites any query-string given in the FORM's ACTION property/field,
unless the method=POST.

Elements are returned in query string if they have a name, even if null or
missing value=...
	But if name is null as in "name= x=y", then not put in query string.
EXCEPT  1) checkboxes: only returned if checked
	2) <submit> items: only returned if clicked.
	3) radioBtns: only returned if at least one is selected.

Repeated elements with same name (even if diff. type) just add 2nd name-val
pair into querystr.  (PHP uses last var setting in string for its internal
var.)

RadioBtns can all be off (unchecked); but can't be multiple because in setting
one to checked, this de-checks the others.

Can have one of a set of RadioBtns spatially separate (but within the form):
may be hard to u., but m-excl. behav. works fine.

Can use java to change a HIDDEN's value, which is then put in arg. string.
But not to change its name i.e. the var= name.  Have to createNode for that?

Elements e.g. radio are still returned even if invisible because
	style='display: none '.  So could use them as another kind of 'hidden'
	input element.  However they can't catch click events while not
	displayed.  But Java can find them on DOM.
	So click on table element, then java to navigate DOM tree ... ??
	[test this]
==========

FORM.action:
action="javascript:" seems to be the only null action.
Adding query args to the 'action': overwritten if GET; passed if POST (but
receiver shouldn't look at them, though they are there in PHP).

=======



========== ========== ========== ==========
C] MY PHP TOOLKIT FOR FORMS. 
----- ----- ----- ----- -----

HOW-TO USE MY PHP-ENHANCED FORMS TOOLKIT
To start a new script/page with forms/menus on, 
	Copy demoforms.php
	Edit the vars at the top to the names and default values you need
	Edit the forms etc. at bottom to suit new case (del. most)

testphp.php is full of sample bits of code

I've printed out PHP doc on patterns.

==========
PHP BASIC BEHAV. W.R.T. FORMS; AND MY EXTENSIONS.

It processes the input request string and sets all the vars specified; 
	overwriting multiple values with the last given.
Need extra code to process multiple values for one var usefully.
Also, simple to get request string e.g. if no varnames mentioned.
Simple to have boolean was/not any request string i.e. first call to page?
Note forms have two methods POST and GET, and these set diff. vars.
	So servers often ignore vars sent by wrong method.
	GET is the default (if not spec).  My scripts tend to use this.
	POST doesn't show the vars in browser URL

Can (I have) impl. default values for a set of vars.
	(only set them if NOT already set by PHP).
	So: work out values and put in PHP vars.
	Then in HTML literal text, call-out to PHP to get the values set in HTML

If you have more than 1 FORM on same web page, then have to preserve memory by
hidden vars in each form, duplicating (previous) state of the other form.

I have implemented a function so that a menu/SELECT can be put up from an array 
	[of display-label => value];
	OR from a list [of values].

==========
My PHP scripting for FORMS.  Overall structure of the script is:
	Param setting by hand editing the script.
	Set php vars: process request string etc.
	Calculate the display (phase 1) into a string
	Output HTML to page.

To do POST to another server from PHP, see doc on:
stream-context-create()

==========
ANCHORS / tags
At least in psy/Apache, presence of a tag suppresses request? part
	AND may stop jumping to tag.
Tag may ONLY be after request part on firefox

I.e. URL syntax must say request ? part before tag# part.

BUT (in apache PHP) the anchor part doesn't appear in PHP at all.
However from the point of view of a calling link, the tag/anchor IS passed on
to the browser to use on whatever HTML the PHP has generated and sent.