User idle detector with session keep-alive, warning dialog, lock screen, url redirection and support for multiple windows and tabs.
npm install jquery-idleTimeout-plusnpm install jquery-idleTimeout-plus
bower install jquery-idleTimeout-plus
...
...
`
$3
* 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)
$3
`
jQuery(document).ready(function() {
IdleTimeoutPlus.start({
idleTimeLimit: 1400
});
});
`
Options
$3
| 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 |
$3
| 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
$3
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!'
`
---
$3
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
`
`
#### 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.
`
Your session is about to expire!
Time remaining:
`
---
$3
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
`
`
#### jQuery UI
`
`
---
$3
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
$3
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
});
});
`
$3
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:
`
...
...
`
$3
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();
});
``