npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jquery-idleTimeout-plus

v0.9.3

Published

User idle detector with session keep-alive, warning dialog, lock screen, url redirection and support for multiple windows and tabs.

Downloads

426

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

crashsenseicrashsensei

Keywords

timeouttime-outtimeridlekeepalivekeep-alivesessionbootstrapbootstrap 3jquerylockscreenlock screenlockjquery-pluginecosystem:jqueryjavascriptmultiple windowsmultiple tabs

Readme

jquery-idleTimeout-plus

User idle detector with session keep-alive, warning dialog, lock screen, url redirection and support for multiple windows and tabs.

Features

  • Highly configurable
  • Multiple window/tab support
  • Callback support for all events (idle,warning,lock screen, logout and redirect)
  • Callback support for dialog/screen creation
  • Support for both jQueryUI and Bootstrap GUI frameworks
  • Modular code supports AMD/CommonJS
  • Attempts to mitigate race conditions with regards to auto logout (what I wouldn't give for cross-window JavaScript semaphores)

Getting Started

Installation

NPM

npm install jquery-idleTimeout-plus

Bower

bower install jquery-idleTimeout-plus

Adding to your website

<head>
    <!-- include jQuery & other necessary dependencies -->
    ...
    <link href="/css/jquery-idleTimeout-plus.css" rel="stylesheet" type="text/css" />
    <script src="/scripts/jquery-idleTimeout-plus.js" type="text/javascript"></script>
    ...
    
</head>

Dependencies

Basic Usage

jQuery(document).ready(function() {
    IdleTimeoutPlus.start({
        idleTimeLimit: 1400
    });
});

Options

Basic Options

| Settings | Type | Default | Descritption | |:--------------|:------:|:---------------------------------|:------------------------------| | idleTimeLimit | int | 1200 (20min) | idle timeout in seconds | | bootstrap | bool | false | enable bootstrap | | warnTimeLimit | int | 180 (3min) | warning timeout in seconds | | warnMessage | string | Your session is about to expire! | warning dialog message | | redirectUrl | string | /timed-out | Redirect URL for user timeout |

Detailed Options

| Setting Name |   | |:----|:----| |Type|Default Value|

General Settings

  • Note: All callback functions receive the IdleTimeoutPlus config object as parameter.

| idleTimeLimit |   | |:----|:----| |int (secs)|1200 (20 min)| The idle time limit in seconds before an action (warning dialog/redirect/etc) is initiated.

| idleCallback |   | |:----|:----| |bool/function|false| Called when the idle timer is started. Use this to close your fully custom warning/lock screens if needed.

| idleCheckHeartbeat |   | |:----|:----| |int (secs)|2| Controls how often the module checks for user activity

| activityEvents |   | |:----|:----| |string|click keypress scroll wheel mousewheel mousemove touchmove| Controls which activity events to detect

| bootstrap |   | |:----|:----| |bool|false| Setting to true enables Bootstrap 3 modals and themes

Warning Settings

| warnEnabled |   | |:----|:----| |bool|true| If set to false the warning period is skipped and the user is either redirected to the timeout URL or shown the lock screen.

| warnTimeLimit |   | |:----|:----| |int (secs)|180 (3 min)| The time limit for the warning period.

| warnCallback |   | |:----|:----| |bool/function|false| Called when the warning period starts. Note: the internal warning dialog will NOT be shown unless this function returns TRUE.

| warnContentCallback |   | |:----|:----| |bool/function|false| This function should return a string that contains the desired structure and content of the warning dialog. See the Custom Content section for more details.

| warnTitle |   | |:----|:----| |string|Session Timeout| The title for the warning dialog. Setting this to null will remove the title bar.

| warnMessage |   | |:----|:----| |string|Your session is about to expire!| The text for the warning dialog.

| warnStayAliveButton |   | |:----|:----| |string|Stay Connected| The text for the warning dialog Stay Alive button.

| warnLogoutButton |   | |:----|:----| |string|Logout| The text for the warning dialog Logout button.

| warnCountdownMessage |   | |:----|:----| |string|Time remaining: {timer}| Text for the warning countdown message. Setting this to null will remove the countdown. See the Custom Content section for more details.

| warnCountdownBar |   | |:----|:----| |bool|false| Enable/disable the warning countdown bar.

Timeout URL Settings

| redirectUrl |   | |:----|:----| |string|/timed-out| URL the user is redirected to after exceeding the timeout.

| logoutUrl |   | |:----|:----| |string|/logout| URL the user is redirected to when clicking the "Logout" button.

| logoutAutoUrl |   | |:----|:----| |string|null| URL the user is redirected to when a logout occurs in another window. If null the logoutUrl value is used.
The purpose of this setting is to help avoid server-side logout race conditions.

Timeout Callback Settings

Note: If a callback function is defined auto url redirection will only occur if the callback function returns true.

| redirectCallback |   | |:----|:----| |bool/function|false| Called after the user exceeds the timeout.

| logoutCallback |   | |:----|:----| |bool/function|false| Called when the user clicks the "Logout" button

| logoutAutoCallback |   | |:----|:----| |bool/function|false| Called when a logout occurs in another window.

Session Keep-Alive Settings

| keepAliveInterval |   | |:----|:----| |int (secs)|600 (10 min)| Controls how often the keepAliveUrl is pinged.

| keepAliveUrl |   | |:----|:----| |string|window.location.href| URL the keep alive ping is sent to.

| keepAliveAjaxType |   | |:----|:----| |string|GET| Sets the desired AJAX query type: GET or POST.

| keepAliveAjaxData |   | |:----|:----| |string|(empty)| The data to send with the keep alive ping request.

Lock Screen Settings

| lockEnabled |   | |:----|:----| |bool|false| If set to true to enable the lock screen functionality. See the Special Situations section for more details.

| lockTimeLimit |   | |:----|:----| |int (secs)|7200 (2 hrs)| The time limit for the lock screen period.

| lockHaltKeepAlive |   | |:----|:----| |bool|true| Controls whether the keep alive pings should be stopped during the lock screen period.

| lockCallback |   | |:----|:----| |bool/function|false| Called when the lock period starts. Note: the internal lock screen will NOT be shown unless this function returns TRUE.

| lockPassCallback |   | |:----|:----| |bool/function|false| This function is REQUIRED if any of the internal lock screen functionality is being used. It will receive to parameters:

  • The submitted user password
  • The config object

The return value of this function is ignored because it is assumed that AJAX will be used to authenticate the password. On a correct password, this function must call IdleTimeoutPlus.rollback() to disable the lock screen. See the Examples page for more information.

| lockTitle |   | |:----|:----| |string|null| The title for the lock screen. Setting this to null will remove the title bar.

| lockUsername |   | |:----|:----| |string|System User| To improve the appearance of the lock screen you should correctly set this to the correct current username.

| lockMessage |   | |:----|:----| |string|Enter your password to unlock the screen| The text for the lock screen.

| lockUnlockButton |   | |:----|:----| |string|UnLock| The text for the lock screen UnLock button.

| lockLogoutButton |   | |:----|:----| |string|Not {username} ?| The text for the lock screen Logout button. This is actually an anchor text link instead of a button. See the Custom Content section for more details.

| lockCountdownMessage |   | |:----|:----| |string|Auto-logout in: {timer}| Text for the lock screen countdown message. Setting this to null will remove the countdown. See the Custom Content section for more details.

| lockBlockUiConfig |   | |:----|:----| |json object|empty| Allows you to customize the BlockUI settings if necessary. See the Custom Content section for more details.

| lockLoadActive |   | |:----|:----| |bool|false| If set to true the lock screen is automatically started. See the Special Situations section for more details.

Lock Screen Settings

| iframesSupport |   | |:----|:----| |bool|false| Enables iFrame support. See the Special Situations section for more details.

| multiWindowSupport |   | |:----|:----| |bool|false| Enables multi-window support. Requires jQuery Storage API to be active. See the Special Situations section for more details.

Custom Content

Countdown Messages & Lock screen Logout text

The options {timer} and {username} are placeholders that are filled with the appropriate content at runtime. {timer} is replaced with a timer showing the remaining minutes and seconds (15m 24s) and {username} is replaced with the value of config.lockUsername. Examples

warnCountdownMessage: 'Redirecting in {timer}'
lockCountdownMessage: '{timer} remaining until logout'
lockLogoutButton: 'Hey! I'm not {username}! Log me out NOW!'

Warning Content

When providing custom content for the warning dialog you must the following classes and element ids to ensure proper function:

| Element Id or Class | Element Type | Description | |:------------------------------|:-------------|:-------------------------------------------------------------------------| | id="jitp-warn-display" | div | Primary parent for the dialog | | class="jitp-countdown-holder" | span | Holds the countdown timer for both the text message and the progress bar | | id="jitp-warn-bar" | div | Countdown progress bar | | id="jitp-warn-logout" | button | Logout button | | id="jitp-warn-alive" | button | Stay Alive button |

Bootstrap

<div class="modal fade" id="jitp-warn-display" data-backdrop="static" data-keyboard="false">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header"><h4 class="modal-title">Session Timeout</h4></div>
            <div class="modal-body">
                <p>Your session is about to expire!</p>
                <p>Time remaining: <span class="jitp-countdown-holder"></span></p>
                <div class="progress">
                    <div id="jitp-warn-bar" class="progress-bar progress-bar-striped active" role="progressbar" style="min-width: 15px; width: 100%;">
                        <span class="jitp-countdown-holder"></span>
                    </div>
                </div>
            </div>
            <div class="modal-footer">
                <button id="jitp-warn-logout" type="button" class="btn btn-default">Logout</button>
                <button id="jitp-warn-alive" type="button" class="btn btn-primary">Stay Connected</button>
            </div>
        </div>
    </div>
</div>

jQuery UI

  • Do not provide the title inside the warning content. Instead be sure to set warnTitle correctly.
  • jQuery UI does not support progress bar labels inside of dialogs so do not include a progress-label element.
  • Unlike Bootstrap many of the elements (buttons/title) are set via the jQuery dialog creation command so the content HTML is considerably simpler.
<div id="jitp-warn-display">
    <p>Your session is about to expire!</p>
    <p>Time remaining: <span class="jitp-countdown-holder"></span></p>
    <div id="jitp-warn-bar"></div>
</div>

Lock Screen Content

When providing custom content for the lock screen you must use the following classes and element ids to ensure proper function:

| Element Id or Class | Element Type | Description | |:------------------------------|:---------------|:-----------------------------------------------| | id="jitp-lock-display" | div | Primary parent for the lock screen | | id="jitp-lock-form" | form | Form element (not required) | | class="jitp-countdown-holder" | span | Holds the countdown timer for the text message | | id="jitp-lock-bar" | div | Countdown progress bar | | id="jitp-lock-pass" | input-password | User password field | | id="jitp-lock-unlock" | button | UnLock button | | id="jitp-lock-logout" | button/anchor | Logout button |

Additionally the display property for the primary parent element (jitp-lock-display) should be set to none: style="display: none;".

Bootstrap

<div id="jitp-lock-display" class="jitp-lock-back" style="display: none;">
    <div class="panel panel-default jitp-lock-panel">
        <div class="panel-heading"><h2 class="panel-title">Screen Locked</h2></div>
        <div class="panel-body">
            <h4>John Doe</h4>
            <p>Enter your password to unlock the screen</p>
            <div class="input-group">
                <input id="jitp-lock-pass" type="password" class="form-control" placeholder="Password..."/>
                <span class="input-group-btn">
                    <button id="jitp-lock-unlock" class="btn btn-primary" type="button">UnLock</button>
                </span>
            </div>
            <a id="jitp-lock-logout" href="javascript:;">Not John Doe ?</a>
        </div>
        <div class="panel-footer">Auto-logout in: <span class="jitp-countdown-holder"></span></div>
    </div>
</div>

jQuery UI

<div id="jitp-lock-display" class="jitp-lock-back" style="display: none;">
    <div class="jitp-lock-panel jitp-lock-jqpanel">
        <header>Screen Locked</header>
        <div class="jitp-lock-jqpanel-body">
            <h2>John Doe</h2>
            <p>Enter your password to unlock the screen</p>
            <div>
                <input id="jitp-lock-pass" type="text" class="form-control" placeholder="Password..."/>
            </div>
            <button id="jitp-lock-unlock" type="button">UnLock</button>
            <a id="jitp-lock-logout" href="javascript:;">Not John Doe ?</a>
        </div>
        <footer>Auto-logout in: <span class="jitp-countdown-holder"></span></footer>
    </div>
</div>

BlockUI Customization

You may override the default BlockUI options by setting the lockBlockUiConfig config element. For mor information refer to the jquery BlockUI documentation.

IdleTimeoutPlus.start({
    lockBlockUiConifg: {
        overlayCSS: {
            backgroundColor: 'HotPink',
        }
    }
});

Special Situations

Multiple Window/Tab support

With multiWindowSupport set to true IdleTimeoutPlus will sync your timeout and logout events across all your client's browser windows & tabs that meet the same-origin policy. Multi-window/tab support is dependent upon jQuery Storage API as local storage is used to sync cross window events. If jQuery Storage API is not found an error will be written to the console and the module will not initialize.

  • When multiple window support is enabled if the user opens a new window it is considered an activity event and the idle timer will be reset and any warning dialogs will be cleared.
  • Be sure to call IdleTimeoutPlus.logout() from your application's logout link/button instead of manually redirecting to your logout page. If this is not done other windows/tabs will not be automatically logged out.
  • If a lock screen is present, opening a new window will NOT clear the lock screen. Instead, the new window will automatically be locked. For more details refer to the Lock screen section further down.
Initialization

No special consideration for configuring/starting the plugin is needed when using the multiWindowSupport option.

jQuery(document).ready(function() {
    IdleTimeoutPlus.start({
        multiWindowSupport: true
    });
});

iFrame support

Like multiple windows, iframe support requires that all your iframes meet the same-origin policy and that the jQuery Storage API plugin is loaded. Additionally, you will need to use the iframes distribution file:

<head>
    <!-- include jQuery & other necessary dependencies -->
    ...
    <link href="/css/jquery-idleTimeout-plus.css" rel="stylesheet" type="text/css" />
    <script src="/scripts/jquery-idleTimeout-plus-iframes.js" type="text/javascript"></script>
    ...
    
</head>

Lock screen support

Enabling lock screen support provides a very nice feature for your users but also introduces some security concerns. Primarily, it is important to realize that anyone familiar with Firebug or Chrome's developer's tools can easily bypass the lock screen. Therefore, Do NOT rely upon this feature to provide hardened security. That being said using a lock screen offers some flexibility between having a user loosing all their form progress after 15min of inactivity and the alternative of keeping the screen unsecured for two hours.

Initialization

To use the lock screen you must 1) Enable the lock screen, 2) Enable multi-window support, 3) Set the lockPassCallback function (if using the internal lock screen feature)

jQuery(document).ready(function() {
    IdleTimeoutPlus.start({
        multiWindowSupport: true,
        lockEnabled: true,
        lockPassCallback: myPasswordVerificationFunction,
    });
});

On your login screen you will need to call the cleanUpLockScreen() function to prevent the user from accidentally receiving a lock screen the moment they login (and subsequently being immediately logged out).

jQuery(document).ready(function() {
    IdleTimeoutPlus.cleanUpLockScreen();
});

About

Bugs or feature requests

Found a problem or would like a feature submit it via GitHub

License

jquery-idleTimeout plus is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License

Acknowledgements

Both Jill Elaine's jquery-idleTimeout and Orangehill's bootstrap-session-timeout have been used as foundations for this jQuery module.