Nonviolent Pigeon Manifestation

    @morr/user-idle

    2.0.0 • Public • Published

    jQuery Idle

    A dead simple jQuery plugin that executes a callback function if the user is idle.

    Usage

    Since this is a simple plugin, the usage is simple too.

    First, add the jquery.idle.js to your document along with jQuery library:

    <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    <script type="text/javascript" src="jquery.idle.js"></script>

    Then, just call the function in the element that you want to track user idleness

    $(document).idle({
      onIdle: function(){
        alert('Since you waited so long, the answer to the Ultimate Question of Life, the Universe, and Everything is 42');
      },
      idle: 10000
    })

    That will display a alert (and a great revelation :D) to the user after 10 seconds of idleness.

    If you want to call some function after user back from idleness, just add the onActive option:

    $(document).idle({
      onIdle: function(){
        alert('I\'m idle');
      },
      onActive: function(){
        alert('Hey, I\'m back!');
      },
      idle: 10000
    })

    To check window visibility, add the onShow or onHide options:

    $(document).idle({
      onHide: function(){
        alert('I\'m hidden');
      },
      onShow: function(){
        alert('Hey, I\'m visible!');
      }
    })

    You can also check if a specific element is idle, actually, you can use any jQuery selector:

    $('header, footer').idle({
      onIdle: function(){
        alert('It\'s been a long time since you don\'t see me');
      },
      idle: 20000
    })

    You can choose which events will be used to "refresh" the idle timer

    $(document).idle({
      onIdle: function(){
        alert('It\'s been a long time since you don\'t see me');
      },
      events: 'mouseover mouseout',
      idle: 30000
    })

    And you can choose if you want to start from an idle state or not

    $(document).idle({
      onIdle: function(){
        alert('It\'s been a long time since you don\'t see me');
      },
      idle: 30000,
      startAtIdle: true
    })

    Options

    onIdle        # callback function that will be triggered when the user gets idle
    onActive      [ default function(){} ] # callback function that will be triggered when the user gets active
    onHide        [ default function(){} ] # callback function that will be triggered when window is hidden
    onShow        [ default function(){} ] # callback function that will be triggered when window is visible
    events        [ default = mousemove keydown mousedown touchstart ] # events that will reset the idle time
    idle          [ default = 60000 ] # idle time in ms
    keepTracking  [ default = true ] # set it to false if you want to track only the first time
    startAtIdle   [ default = false ] # if you want to start idle, set it to true
    recurIdleCall [ default = false ] # by default use setTimeout, set it to true if you want to use setInterval
    

    Events

    "idle:stop": will stop and remove user tracking
    

    Vanilla

    jQuery Idle also provide a non-jQuery version. Use the vanilla.idle.js file instead, and initialize it like this:

    idle().start();
    

    Options are the same as with the jQuery version:

    idle({
      onIdle: function (){
        console.log('idle !');
      },
      // ...
    }).start();
    

    Changelog

    1.3.0

    • Replacing the jquey dependency for a peerDependency as mentioned on the issue #31

    1.2.9

    • Fixed jquery vulnerability.

    1.2.8


    • Added the jQuery dependency to the package.json (#31) and fix the documentation format.

    1.2.7


    • Corrected the logic in resetTimeout. Setting the idle = false before calling the onActive handler prevents looping when calling idle:stop in the onActive handler. (@ashupp)

    1.2.6


    1.2.5


    • Added the recurIdleCall option to choose between setTimeout ou setInterval (thanks kgaikwad)

    1.2.4


    • Changed keypress to keydown to also detect arrow keys on a keyboard press, and not just the normal A-Z keys (thanks carlblock)

    1.2.3


    • Added 'idle:stop' event to stop and remove user tracking (thanks D3add3d and zachdixon)

    1.2.2


    • The logic behind 'keepTracking' was a total mess. Rewrote the functionality to work as it should
    • Change the default 'keepTracking' value. Now is set to true

    1.2.1


    • Added the 'startAtIdle' option so you can choose if you want to start idle or not (@hugohil)

    1.2.0


    • Added the 'onHide' and 'onShow' callback functions to be executed when window changes visibility (@DanH42)

    1.1.0


    • Renamed the 'callback' setting to 'onIdle'
    • Added the 'onActive' callback function to be executed when user back from idleness (thanks @joelsouza for the tip)

    1.0.0


    First basic version

    Install

    npm i @morr/user-idle

    DownloadsWeekly Downloads

    5

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    9.83 kB

    Total Files

    4

    Last publish

    Collaborators

    • morr