Return to BEFOREUNLOAD.txt CVS log

Up to [Repository] / kupuMPIWG / doc

Annotation of kupuMPIWG/doc/BEFOREUNLOAD.txt, revision 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.