169 lines
4.7 KiB
Plaintext
169 lines
4.7 KiB
Plaintext
=================
|
|
BeforeUnload Tool
|
|
=================
|
|
|
|
The BeforeUnload tool will check forms when navigating away from a
|
|
page and will warn a user if they are about to lost changes and give
|
|
them the option to remain editing the page.
|
|
|
|
How to use the tool
|
|
===================
|
|
|
|
The tool will install itself automatically provided the javascript
|
|
is loaded, and provided no other handler has been installed for the
|
|
window.onbeforeunload event.
|
|
|
|
To test for the presence of the tool and use it if it is present use
|
|
the following code::
|
|
|
|
var beforeunloadTool = window.onbeforeunload && window.onbeforeunload.tool;
|
|
if (beforeunloadTool) { ... };
|
|
|
|
Although the tool is installed by default, it does not check any
|
|
forms unless they are added. Use the addForm method to add a single
|
|
form or addForms method to add multiple forms. When a form is added,
|
|
its onsubmit method will be hooked by the tool: if your form needs to
|
|
perform its own onsubmit processing you must replace this event
|
|
after calling addForm.
|
|
|
|
The following input field types may be checked::
|
|
|
|
<input type="text">
|
|
<textarea>
|
|
<input type="radio">
|
|
<input type="checkbox">
|
|
<input type="password">
|
|
<select>
|
|
<select multiple>
|
|
<input type="hidden">
|
|
|
|
Single selection fields where nothing was initially selected are
|
|
considered to have changed if the first entry is not selected. Single
|
|
selection fields where multiple entries were marked as selected
|
|
initially are always considered changed.
|
|
|
|
Field which do not have a `name` attribute are assumed to be
|
|
client-side only (as they are not submitted to the server) and are
|
|
ignored when checking.
|
|
|
|
Note that hidden fields are checked for changes although a bug in
|
|
Mozilla means that this is done by storing their original value when
|
|
the handler is notified of the form.
|
|
|
|
These field types are always assumed to be unchanged::
|
|
|
|
<input type="button">
|
|
<input type="file">
|
|
<input type="image">
|
|
<input type="reset">
|
|
<input type="submit">
|
|
|
|
Handler functions return false to indicate there is no change to be
|
|
lost, true to indicate that something has changed and the default
|
|
message should be displayed, or they may return a string to show a
|
|
custom message. Once a handler function has returned a value other
|
|
than false no other handler functions are called.
|
|
|
|
API
|
|
===
|
|
|
|
Global variables
|
|
----------------
|
|
|
|
None. The BeforeUnload tool does not create or modify any global
|
|
javascript variables. The only way to access it is through the
|
|
onbeforeunload event of the window object.
|
|
|
|
|
|
Methods
|
|
-------
|
|
|
|
isAnyFormChanged()
|
|
++++++++++++++++++
|
|
|
|
Calls isElementChanged() for all watched forms and returns the first non-false
|
|
value. This is the first handler function called when the page is
|
|
unloading.
|
|
|
|
addHandler(fn)
|
|
++++++++++++++
|
|
|
|
Appends another handler function to be called when the page is
|
|
unloading. The handler should not assume anything about the value of
|
|
'this' when it is called.
|
|
|
|
Example::
|
|
|
|
var initialBody = ibody.innerHTML;
|
|
beforeunloadTool.addHandler(function() {
|
|
return ibody.innerHTML != initialBody;
|
|
});
|
|
|
|
|
|
onsubmit()
|
|
++++++++++
|
|
|
|
This method is used as the default form.onsubmit event. If you replace
|
|
form.onsubmit you should call beforeunloadTool.onsubmit() after
|
|
validating the form.
|
|
|
|
addForm(form)
|
|
+++++++++++++
|
|
|
|
Enables checking for a single form and sets the form's onsubmit handler.
|
|
|
|
addForms(el1, el2, ...)
|
|
+++++++++++++++++++++++
|
|
|
|
Finds all forms which are the specified elements or children of the
|
|
elements at any depth and enables checking for those forms.
|
|
|
|
removeForms(el1, el2, ...)
|
|
++++++++++++++++++++++++++
|
|
|
|
Finds all forms in the parameters and disables checking for those
|
|
forms.
|
|
|
|
isElementChanged(element)
|
|
+++++++++++++++++++++++++
|
|
|
|
Returns true (or a string) if the specified element has changed, false
|
|
if it has not. element may be a form or a control on form.
|
|
|
|
Properties
|
|
----------
|
|
|
|
submitting
|
|
++++++++++
|
|
|
|
Set true by the default form onsubmit handler. If you cancel form
|
|
submission you must set it false.
|
|
|
|
chkId
|
|
+++++
|
|
|
|
beforeunloadTool.chkId is an object which may contain methods whose
|
|
names are the same as the ids of form controls. By default there are
|
|
no such methods. Add a method if you wish to override checking for a
|
|
single control. the method should return true or a string if the field
|
|
has changed, false if it has not.
|
|
|
|
For example, to ignore a control which is only used client-side::
|
|
|
|
beforeunloadTool.chkId['kupu-tb-styles'] = function() { return false; }
|
|
|
|
chkType
|
|
+++++++
|
|
|
|
This property contains methods which check a field based on its 'type'
|
|
attribute. For example, to turn off checking for all radio buttons::
|
|
|
|
beforeunloadTool.chkType['radio'] = function() { return false; }
|
|
|
|
The chkType method is not called if a matching chkId method is found.
|
|
|
|
message
|
|
+++++++
|
|
|
|
This string is displayed if a handler function returns true.
|