Return to BEFOREUNLOAD.txt CVS log

Up to [Repository] / kupu / doc

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.