Annotation of kupu/doc/BEFOREUNLOAD.txt, revision 1.1.1.1
1.1 dwinter 1: =================
2: BeforeUnload Tool
3: =================
4:
5: The BeforeUnload tool will check forms when navigating away from a
6: page and will warn a user if they are about to lost changes and give
7: them the option to remain editing the page.
8:
9: How to use the tool
10: ===================
11:
12: The tool will install itself automatically provided the javascript
13: is loaded, and provided no other handler has been installed for the
14: window.onbeforeunload event.
15:
16: To test for the presence of the tool and use it if it is present use
17: the following code::
18:
19: var beforeunloadTool = window.onbeforeunload && window.onbeforeunload.tool;
20: if (beforeunloadTool) { ... };
21:
22: Although the tool is installed by default, it does not check any
23: forms unless they are added. Use the addForm method to add a single
24: form or addForms method to add multiple forms. When a form is added,
25: its onsubmit method will be hooked by the tool: if your form needs to
26: perform its own onsubmit processing you must replace this event
27: after calling addForm.
28:
29: The following input field types may be checked::
30:
31: <input type="text">
32: <textarea>
33: <input type="radio">
34: <input type="checkbox">
35: <input type="password">
36: <select>
37: <select multiple>
38: <input type="hidden">
39:
40: Single selection fields where nothing was initially selected are
41: considered to have changed if the first entry is not selected. Single
42: selection fields where multiple entries were marked as selected
43: initially are always considered changed.
44:
45: Field which do not have a `name` attribute are assumed to be
46: client-side only (as they are not submitted to the server) and are
47: ignored when checking.
48:
49: Note that hidden fields are checked for changes although a bug in
50: Mozilla means that this is done by storing their original value when
51: the handler is notified of the form.
52:
53: These field types are always assumed to be unchanged::
54:
55: <input type="button">
56: <input type="file">
57: <input type="image">
58: <input type="reset">
59: <input type="submit">
60:
61: Handler functions return false to indicate there is no change to be
62: lost, true to indicate that something has changed and the default
63: message should be displayed, or they may return a string to show a
64: custom message. Once a handler function has returned a value other
65: than false no other handler functions are called.
66:
67: API
68: ===
69:
70: Global variables
71: ----------------
72:
73: None. The BeforeUnload tool does not create or modify any global
74: javascript variables. The only way to access it is through the
75: onbeforeunload event of the window object.
76:
77:
78: Methods
79: -------
80:
81: isAnyFormChanged()
82: ++++++++++++++++++
83:
84: Calls isElementChanged() for all watched forms and returns the first non-false
85: value. This is the first handler function called when the page is
86: unloading.
87:
88: addHandler(fn)
89: ++++++++++++++
90:
91: Appends another handler function to be called when the page is
92: unloading. The handler should not assume anything about the value of
93: 'this' when it is called.
94:
95: Example::
96:
97: var initialBody = ibody.innerHTML;
98: beforeunloadTool.addHandler(function() {
99: return ibody.innerHTML != initialBody;
100: });
101:
102:
103: onsubmit()
104: ++++++++++
105:
106: This method is used as the default form.onsubmit event. If you replace
107: form.onsubmit you should call beforeunloadTool.onsubmit() after
108: validating the form.
109:
110: addForm(form)
111: +++++++++++++
112:
113: Enables checking for a single form and sets the form's onsubmit handler.
114:
115: addForms(el1, el2, ...)
116: +++++++++++++++++++++++
117:
118: Finds all forms which are the specified elements or children of the
119: elements at any depth and enables checking for those forms.
120:
121: removeForms(el1, el2, ...)
122: ++++++++++++++++++++++++++
123:
124: Finds all forms in the parameters and disables checking for those
125: forms.
126:
127: isElementChanged(element)
128: +++++++++++++++++++++++++
129:
130: Returns true (or a string) if the specified element has changed, false
131: if it has not. element may be a form or a control on form.
132:
133: Properties
134: ----------
135:
136: submitting
137: ++++++++++
138:
139: Set true by the default form onsubmit handler. If you cancel form
140: submission you must set it false.
141:
142: chkId
143: +++++
144:
145: beforeunloadTool.chkId is an object which may contain methods whose
146: names are the same as the ids of form controls. By default there are
147: no such methods. Add a method if you wish to override checking for a
148: single control. the method should return true or a string if the field
149: has changed, false if it has not.
150:
151: For example, to ignore a control which is only used client-side::
152:
153: beforeunloadTool.chkId['kupu-tb-styles'] = function() { return false; }
154:
155: chkType
156: +++++++
157:
158: This property contains methods which check a field based on its 'type'
159: attribute. For example, to turn off checking for all radio buttons::
160:
161: beforeunloadTool.chkType['radio'] = function() { return false; }
162:
163: The chkType method is not called if a matching chkId method is found.
164:
165: message
166: +++++++
167:
168: This string is displayed if a handler function returns true.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>