[Sommaire] [Imprimer]

   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.