Types
Nag
A simple nag appears in the DOM where it is declared
Look, I am a nag!
Title
A nag can have a title
Welcome to the nag module
Look, I am a nag!
Fixed Nag
A fixed nag appears at the top of the screen
Look, i am a fixed nag!
/*
persist:true is used to ignore dismiss storage when closing
for demo purposes here, not related to 'fixed' variant
*/
$('#fixednag')
.nag({
persist:true
})
;
A fixed nag can appear at the bottom of the screen
Look, I am a bottom fixed nag!
$('#bottomfixednag')
.nag({
persist:true
})
;
Overlay Nag
An overlay nag is absolute positioned and appears at the top of the parent DOM node
An overlay nag can appear at the bottom of the parent node
Groups
Nags
A group of nags can be formatted to appear together
First nag
Second nag
Third nag
Variations
Colored
A nag can be formatted to be different colors
Red
Orange
Yellow
Olive
Green
Teal
Blue
Violet
Purple
Pink
Brown
Black
Inverted
A nag can be formatted to appear inverted
Inverted
This nag has inverted colors
Size
A nag can have different sizes
Mini nag
Tiny nag
Small nag
Large nag
Big nag
Huge nag
Massive nag
Examples
// Automatically shows on init if cookie isn't set
$('.cookie.nag')
.nag({
key : 'accepts-cookies',
value : true
})
;
// Wont re-appear unless cleared
$('.cookie.nag')
.nag('show')
;
// Clears cookie so nag shows again
$('.cookie.nag')
.nag('clear')
;
Usage
Nags are used to present a user with a one time message which will persist until a user acknowledges the message. This can be used for providing notices like the site's use of cookies, an important change to a site like a security breach.
Fomantic's nag component provides built in options for ensuring a nag is only displayed once. You can trigger an API endpoint on dismissal, in order to store a value in your database, or you can use localstorage, sessionstorage or cookie value to make sure that a particular computer does not receive the nag again.
Initializing a Nag
$('.ui.nag')
.nag()
;
Welcome to the nag module
Some additional Info here
Behaviors
All the following behaviors can be called using the syntax:
$('.ui.nag').nag('behavior', argumentOne, argumentTwo...);
| show | Shows the nag, if it isn't dismissed and no expiration date is set in storage |
| hide | Hides the nag |
| dismiss | Dismisses the nag and sets the expiration date into the given storage to prevent the nag being shown the next time |
| clear | Deletes an already set expiration date, so the nag gets shown the next time |
| destroy | Destroys instance and removes all events |
Settings
Nag Settings
Settings to configure nag behavior
| Setting | Default | Description |
|---|---|---|
| persist | false | true will show the nag, even if it is already dismissed, but will keep a set expiration date intact |
| displayTime | 0 | Time in milliseconds until nag gets automatically hidden. Zero requires manually dismissal, otherwise hides on its own |
| context | body | Selector or jquery object specifying the area to attach the nag to |
| detachable | false | If set to true will re-attach the nag to the given context node |
| expires | 30 | Amount of days or a Date Object until expiration of cookie/localstorage |
| domain | false | cookie option |
| path | / | cookie option |
| secure | false | cookie option |
| samesite | false | cookie option |
| storageMethod | cookie | Storage to store the expiration date when the nag is dismissed. Can be either cookie, localstorage or sessionstorage |
| key | nag | Key to store in dismissed localstorage/cookie |
| value | dismiss | Value to store in dismissed localstorage/cookie |
| expirationKey | ExpirationDate | Key suffix to support expiration in localstorage |
| animation |
animation : {
show : 'slide',
hide : 'slide'
}
|
Animation transition style for open/close animation. Can be either slide or fade |
| duration | 500 | Duration of open/close animation |
| easing | easeOutQuad | Easing of open/close animation. EaseOutQuad is included with nag, for additional options you must include easing equations. |
Callbacks
Callbacks specify a function to occur after a specific behavior.
| Parameters | Description | |
|---|---|---|
| onShow | $module | Callback before nag is shown. Returning false from this callback will cancel the nag from showing. |
| onVisible | $module | Callback after nag is shown. |
| onHide | $module | Callback before nag is hidden. Returning false from this callback will cancel the nag from hiding. |
| onHidden | $module | Callback after nag is hidden. |
DOM Settings
DOM settings specify how this module should interface with the DOM
| Setting | Default | Description |
|---|---|---|
| namespace | nag | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| selector |
selector : {
close : '> .close.icon'
}
|
DOM Selectors used internally |
| className |
className : {
bottom : 'bottom',
fixed : 'fixed'
}
|
Class names used to attach style to state |
Debug Settings
Debug settings controls debug output to the console
| Setting | Default | Description |
|---|---|---|
| name | Nag | Name used in debug logs |
| silent | false | Silences all console output including error messages, regardless of other debug settings. |
| debug | false | Provides standard debug output to console |
| performance | true | Provides standard debug output to console |
| verbose | false | Provides ancillary debug output to console |
| errors |
error: {
noStorage : 'Unsupported storage method',
method : 'The method you called is not defined.',
setItem : 'Unexpected error while setting value',
expiresFormat : '"expires" must be a number of days or a Date Object'
}
|
|