webFormControl v1.08
Readme
Author: Dave Transom
Date: 31/01/2003
Included Files:
- scriptOptimise.v2.5.vbs
For optimising .js files (lowers filesize)
- readme.txt
This document
- changelog.txt
A history of changes through each version :/
- livedonkey.webFormControl.js
A main script file (optimised of course)
- livedonkey.webFormControl.source.js
The main script file laid out with comments
- livedonkey.webFormControl.optimised.js
The optimised source file (use this one)
- popupWindow.css
CSS file used in samples (notes inside)
- popupWindow.another.example.css
An extra example (used on hexymusic.com)
- samp.webFormControl.toy.html
Toy for playing with the various options etc
- samp.webFormControl.sample.html
A working example
Installation Instructions:
Unzip the entire contents of the script and check out this readme and the
included samples. When you are ready to go on your own forms, simply include
the "webFormControl.js" file and call fcheckRequiredFields( this );
from the onsubmit event of your form.
e.g. <form action="desitination.ext" method="post"
onsubmit="return webFormControl( this );" />
Upgrading Instructions:
To upgrade simply extract/unzip the "livedonkey.webFormControl.js"
file and replace your existing file with it.
Customizing (and using "scriptOptimise.v2.5.vbs"):
Feel free to customize these scripts as you see fit. There is a convenient
source file filled with voluptuous comments on why things do what. Due to the
nature on comments and the general size of this script, you might want to use
the "scriptOptimise.v2.5.vbs" script, which removes all the unneeded
things for running a production script.
To use it, simply drag & drop the desired .js file onto the "scriptOptimise.v2.5.vbs"
file. It will output a new file ending in ".optimised.js" and in the
case of our "livedonkey.webFormControl.source.js" file, it will write
"livedonkey.webFormControl.optimised.js".
Note: You will need windows scripting host installed on your puter which is
a microsofty thing, so go try and get it if it doesn't work. Best thing to do
is give it a blast, and if it gives an error, you need to install, otherwise
you're sweet :)
Remember when using this script for optimising other files, ensure that you
keep a copy of your source file safe... just in case things get chunky!
Configuration:
Following are the configuration properties etc for your form. The only required
field is requiredRules.
Remember an asterisk(*) means the property is optional.
requiredRules: This is the ONLY required field for the script to work.
If left out or spelt incorrectly, function will return true.
usage:
<input type="hidden" name="requiredRules" value="FieldName:min-max:directive;
FieldName2;" />
syntax: FieldName[:Attribute][:Attribute];
FieldName is required and case-sensitive
rules:
FieldName:
Required as the first entry per rule and before any colons(:). If only FieldName
is specified (with no attributes), then the FieldName value must not be nothing
e.g. not "".
Attribute(s):
You can specify one two or more attributes, but only the last valid numeric/min-max
attribute and directive attribute will be used.
Range attributes:
n, -n: a maximum number, where n is the maximum field length.
n-nn: a number range, where field length must be between n and nn characters
long.
n-: a minimum number, where n is the minimum field length.
Directive attributes:
num: Field must be numeric.
alp: Field must not be a number. e.g. "111" will give an
error, but "111a" is okay.
ema: Field must be a valid email. I recommend also using attribute
"7-" to ensure length is closer to a valid email address. If you combine
attribute "0-" then this field becomes optional i.e. it will not give
an error if the field is blank (e.g. "") but if something is entered,
will be checked for validity.
equ: FieldName value must be equal to the value in "FieldName_check"
(note the _check on the end of another field). If FieldName_check does not exist,
it will give an error in the debugging info.
eqn: As above, but both values must be numeric.
eqm: As above, but both values must be email addresses.
note: Separate multiple rules with a semi-colon(;)
requiredDebug: *
This property tells the script to show debugging information. It will tell
you all the elements in your "requiredRules" exist, whether there
are conflicts etc.
Set this to 0 to turn it off, 1 to debug (or any other value other than 0).
usage:
<input type="hidden" name="requiredDebug" value="1"
/>
note: I recommend using the "popup" message type (see below)
for debugging as it displays with a better format then say just an alert box.
requiredIgnorePrefix: *
This property gives a list of field prefixes that should be ignored when displaying
the FieldName to the user. e.g. If you send the form to an server parsed script
you may want to prefix input boxes with txt (txtFieldName) so your script processes
the correct fields. The user will only see FieldName.
Separate multiple prefixes with a comma(,).
usage:
<input type="hidden" name="requiredIgnorePrefix" value="txt,rad,opt,rad,chk,sel"
/>
requiredMsgType: *
This sets the format that the message will be displayed as. If this is not
specified it defaults to "alert"
usage:
<input type="hidden" name="requiredMsgType" value="popup"
/>
values:
alert: Shows message in a Javascript alert box.
popup: Opens a new window and displays message with CSS.
span: Displays message inside a layer in the current page identified
by id="requiredOutput". e.g. <div name="requiredOutput"
id="requiredOutput"></div>.
To allow CSS to work with this you must include the appropriate classes in your
page. (see CSS below for classes etc.)
requiredMsgTitle: *
If specified message will appear at the very top of the alert. If message
type is popup or span then this can be formatted by the class ".text-title".
If the type is a popup, then this also appears as the title of the new window.
usage:
<input type="hidden" name="requiredMsgTitle" value="An
error occurred" />
requiredMsgHead: *
If specified message will appear directly under the title. This can be formatted
by CSS using the class ".text-head".
usage:
<input type="hidden" name="requiredMsgHead" value="You
have missed some stuff man! Please check out your entries and amend the errors
found below." />
requiredMsgFoot: *
If specified this message will appear at the bottom of the alert. This can
be formatted by CSS using the class ".text-foot". If you wish to add
HTML code to this field, remember to URL encode the contents as extra ' and
" will screw this script with no debugging ;)
usage:
<input type="hidden" name="requiredMsgFoot" value="<a
href=%22javascript:self.close();%22>Close</a> this window to continue"
/>
requiredMsgCSS: *
The CSS file to include for popup windows. See inside the CSS file for comments
on formatting.
usage:
<input type="hidden" name="requiredMsgCSS" value="popupWindow.css"
/>
top