Jquery-idleTimeout-plus NPM

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

jQuery +1.7
jQuery UI +1.9 or Bootstrap 3
jQuery Storage API (for iFrame or Multi-window support)
jQuery BlockUI (for lock screen support)

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.

timeout time-out timer idle keepalive keep-alive session bootstrap bootstrap 3 jquery lockscreen lock screen lock jquery-plugin ecosystem:jquery javascript multiple windows multiple tabs

@infinitebrahmanuniverse/nolb-jquery-i @everything-registry/sub-chunk-1971

8 years ago

8 years ago

8 years ago

8 years ago