hubzilla_ynh/sources/library/jquery.AreYouSure/README.md

Are You Sure? - A light "dirty forms" JQuery Plugin

Version: 1.9

Are-you-sure (jquery.are-you-sure.js) is simple light-weight "dirty form" JQuery Plugin for modern browsers. It helps prevent users from losing unsaved HTML Form changes by promoting the user to save/submit.

It's simple to use. Just add the following line to your page's ready function:

$('form').areYouSure();

Are-you-sure is a minimal plugin for modern browsers. There are plenty of "dirty forms" implementations out there, however they all seemed very heavyweight and over-engineered...! Most were written some time back and contain many 'hacks' to support legacy browsers, and/or rely on other fat dependencies such as FaceBox or jQueryUI. Are-you-sure solves this by doing this simple task in the simplest possible way.

Are-you-sure is as simple as it gets:

• 100% JS with zero dependencies and no external CSS.
• Leverages onBeforeUnload to detect all page/browser exit events.
• Works on forms of any size.
• Correct state management - if a user edits then restores a value, the form is not considered dirty.
• Easy to understand - less than a "terminal screen" of code!
• Graceful degradation on legacy browsers (i.e. if you're running an old browser... remember to save :-)

###Basic Usage

$(function() {

    // Enable on all forms
    $('form').areYouSure();

    // Enable on selected forms
    $('form.dirty-check').areYouSure();

    // With a custom message
    $('form').areYouSure( {'message':'Your profile details are not saved!'} );

}

To ignore selected fields from the dirtyness check:

  <form id="myForm" name="myform" action="/post" method="post">

    Field 1: (checked)  <input type="text" name="field1"> <br />
    Field 2: (ignored): <input type="text" name="field2" data-ays-ignore="true"> <br />
    Field 3: (ignored): <input type="text" name="field3" class="ays-ignore"> <br />

    <input type="submit" value="Submit">

  </form>

###Advanced Usage

$(function() {

    /*
    *  Make Are-You-Sure "silent" by disabling the warning message 
    *  (tracking/monitoring only mode). This option is useful when you wish to 
    *  use the dirty/save events and/or use the dirtyness tracking in your own 
    *  beforeunload handler.
    */
    $('form').areYouSure( {'silent':true} );
	
    /*
    *  Dirtyness Change Events
    *  Are-You-Sure fires off "dirty" and "clean" events when the form's state
    *  changes. You can bind() or on(), these events to implement your own form
    *  state logic.  A good example is enabling/disabling a Save button.
    *
    *  "this" refers to the form that fired the event.
    */
    $('form').on('dirty.areYouSure', function() {
      // Enable save button only as the form is dirty.
      $(this).find('input[type="submit"]').removeAttr('disabled');
    });
    $('form').on('clean.areYouSure', function() {
      // Form is clean so nothing to save - disable the save button.
      $(this).find('input[type="submit"]').attr('disabled', 'disabled');
    });

    /*
    *  It's easy to test if a form is dirty in your own code - just check
    *  to see if it has a "dirty" CSS class.
    */
    if ($('#my-form').hasClass('dirty')) {
        // Do something
    }

    /*
    *  If you're dynamically adding new fields/inputs, and would like to track 
    *  their state, trigger Are-You-Sure to rescan the form like this:
    */
    $('#my-form').trigger('rescan.areYouSure');

    /*
    *  If you'd like to reset/reinitialize the form's state as clean and 
    *  start tracking again from this new point onwards, trigger the
    *  reinitalize as follows. This is handy if say you've managing your
    *  own form save/submit via asyc AJAX.
    */
    $('#my-form').trigger('reinitialize.areYouSure');

    /*
    *  In some situations it may be desirable to look for other form
    *  changes such as adding/removing fields. This is useful for forms that
    *  can change their field count, such as address/phone contact forms.
    *  Form example, you might remove a phone number from a contact form
    *  but update nothing else. This should mark the form as dirty.
    */
    $('form').areYouSure( {'addRemoveFieldsMarksDirty':true} );
    
    /*
    *  Sometimes you may have advanced forms that change their state via
    *  custom JavaScript or 3rd-party component JavaScript. Are-You-Sure may 
    *  not automatically detect these state changes. Examples include:
    *     - Updating a hidden input field via background JS.
    *     - Using a [rich WYSIWYG edit control](https://github.com/codedance/jquery.AreYouSure/issues/17).
    *  One solution is to manually trigger a form check as follows:
    */
    $('#my-form').trigger('checkform.areYouSure');
	
    /*
    *  As an alternative to using events, you can pass in a custom change 
    *  function.
    */
    $('#my-adv-form').areYouSure({
        change: function() {
              // Enable save button only if the form is dirty. i.e. something to save.
              if ($(this).hasClass('dirty')) {
                $(this).find('input[type="submit"]').removeAttr('disabled');
              } else {
                $(this).find('input[type="submit"]').attr('disabled', 'disabled');
              }
            }
    });

    /*
    *  Mixing in your own logic into the warning.
    */
    $('#my-form').areYouSure( {'silent':true} );
    $(window).on('beforeunload', function() {
        isSunday = (0 == (new Date()).getDay());
        if ($('#my-form').hasClass('dirty') && isSunday) {
            return "Because it's Sunday, I'll be nice and let you know you forgot to save!";
        }
    }
    
}

The demo page shows the advanced usage options in more detail.

###Install Are-You-Sure is a light-weight jQuery plugin - it's a single standalone JavaScript file. You can download the jquery.are-you-sure.js file and include it in your page. Because it's so simple it seems a shame to add an extra browser round trip. It's recommended that you consider concatenating it with other common JS lib files, and/or even cut-n-pasting the code (and license header) into one of your existing JS files.

For experimental Mobile Safari support, also include ays-beforeunload-shim.js (see Known Issues below).

Are-you-sure may also be installed with Bower:

$ bower install jquery.are-you-sure

If you're using, or like, Are-you-sure make sure you star/watch this project so you can stay up-to-date with updates.

###Demo This demo page hosts a number of example forms.

###Supported Browsers Are-you-sure has been tested on and fully supports the following browsers:

• IE 9 through 11
• Google Chrome (versions since 2012)
• Firefox (versions since 2012)
• Safari (versions since 2012)

Experimental support is available on iOS and Opera via the beforeunload shim (see below).

###Known Issues & Limitations

####Mobile Safari and Opera The windows.beforeunload event is not supported on iOS (iPhone, iPad, and iPod). An experimental shim offering partial beforeunload emulation is provided to help plug this gap. It works by scanning the page for anchor links and augments the default behaviour to first check with Are-you-sure before navigating away. To use, simply include ays-beforeunload-shim.js in your page.

####Firefox The custom message option may not work on Firefox (Firefox bug 588292).

###Development The aim is to keep Are-you-sure simple and light. If you think you have a good idea which is aligned with this objective, please voice your thoughts in the issues list.

####Pull Requests If possible, please submit your pull request against the most recent dev-* branch rather than master. This will make it easier to merge your code into the next planned release.

####Running tests

$ npm install
$ npm test

###Release History

2014-08-13 (1.9) - This is a minor bugfix release:

• Addressed issue #45 seen with empty select fields.
• Thanks valgen and tus124 for the contribution.

2014-06-22 (1.8) - This is a minor bugfix release:

• Fixed NPE that may occur when using a 'multiple' option field.
• Minor timing tweak to help mitigate bypass issue raised in #45
• Thanks apassant and amatenkov for the contribution.

2014-05-28 (1.7)

• Fixed multiple warning dialogs that may appear on IE and recent versions of Chrome
• Experimental support for iOS Mobile Safari (via a beforeunload shim)
• Various minor fixes (e.g. support input fields with no type=)
• Minor performance improvements on pages with multiple forms
• Improved documentation and examples
• Thanks to lfjeff and aqlong for the contribution and ideas!

2014-02-07 (1.6)

• Add field count tracking (addRemoveFieldsMarksDirty) (contrib jonegerton)
• Added event to manually trigger a form check/recheck (contrib jonegerton)
• Thanks to jonegerton for the contribution!

2013-11-15 (1.5)

• Added support for HTML5 input field types. (contrib albinsunnanbo)
• New option to reinitialize/reset the dirty state. This is handy if you're managing your own async submit/save using AJAX. (contrib albinsunnanbo)
• Thanks to albinsunnanbo for the contribution!

2013-10-2 (1.4)

• Added dirty and clean "events"
• Added an option to disable the message (dirty tracking only)
• Added an option to rescan a form to look/detect any new fields

2013-07-24 - Minor fix - don't fail if form elements have no "name" attribute.

2013-05-14 - Added support for form reset buttons (contributed by codev).

2013-05-01 - Added support for hidden and disabled form fields.

2013-02-03 - Add demo page.

2013-01-28 - Add change event support and a demo page.

2012-10-26 - Use dashes in class names rather than camel case.

2012-10-24 - Initial public release.

###Prerequisites jQuery version 1.4.2 or higher. 2.0+ or 1.10+ recommended.

###License The same as JQuery...

jQuery Plugin: Are-You-Sure (Dirty Form Detection)
https://github.com/codedance/jquery.AreYouSure/

Copyright (c) 2012-2014, Chris Dance - PaperCut Software http://www.papercut.com/
Dual licensed under the MIT or GPL Version 2 licenses.
http://jquery.org/license