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
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;".
<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.
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.
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)
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).