Skip to Content

Wiki source code of Notification Messages

Last modified by Lucas Charpentier on 2026/10/08 09:42
Hide last authors
Guillaume Delhumeau 3.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Oana Florea 1.1 4
5 {{warning}}
6 This tutorial is a work in progress.
7 {{/warning}}
8
9 {{info}}
10 This is a Javascript widget bundled by default with the XWiki platform.
11 {{/info}}
12
Manuel Leduc 12.1 13 = Reference =
14
15 See the [[Notification Message API reference>>documentation.xs.dev.front-end.notification.api.WebHome]] for an exhaustive documentation of this component API.
16
Oana Florea 1.1 17 = Usage =
18
19 The XWiki notification widget is a general purpose notification JavaScript class, displaying a simple message for the user, at the bottom of the screen.
20 Features:
21
22 * Several default aspects: ##plain##, ##info##, ##warning##, ##error##, ##inprogress##, ##done##.
23 * Stacking of multiple notifications on the screen.
24 * Possibility to replace a notification with another one, preserving the position.
25 * Automatic hide after a configurable period of time.
26 * Configurable icon, background and text color.
27
Lucas Charpentier 17.1 28 {{version since="18.9.0RC1"}}The preferred way to display a notification is to call ##XWiki.widgets.Notification.show(text, type, options)##, which takes the same parameters as the constructor below and returns the displayed notification. See the [[API documentation>>xwiki:documentation.xs.dev.front-end.notification.api.WebHome#Hshow28text2Ctype2Coptions29]].{{/version}}
29
Oana Florea 1.1 30 To display a notification, it suffices to create a new ##XWiki.widgets.Notification## object. Constructor parameters:
31
32 |=Parameter|=Description|=Optional
33 |##text##|The notification text|no
34 |##type##|The notification type, one of ##plain##, ##info##, ##warning##, ##error##, ##inprogress##, ##done##. If an unknown or no type is passed, ##plain## is used by default.|yes
35 |##options##|Additional configuration; supported options:(((
36 * ##timeout##: number of seconds to keep the notification on the screen. Use 0 or false to keep it until manually removed.
Manuel Leduc 12.1 37 * ##inactive##: don't show the notification when the object is created, manually call ##show## later>  
Oana Florea 1.1 38 * ##icon##: a custom image to use
39 * ##color##: a custom color for the text
40 * ##backgroundColor##: a custom color for the background
Sergiu Dumitriu 4.1 41 * ##onHide##: a custom function to call when the notification disappears
Manuel Leduc 13.1 42 * {{version since="17.10.9,18.4.0RC1"}}##textHtml##: enable the ##text## to be interpreted as HTML (defaults to ##false##){{/version}}
Oana Florea 1.1 43 )))|yes
44
45 Default parameters for the predefined notification types:
46
47 |=Notification Type|=Parameter Values
48 |##plain##|(((
49 * ##timeout##: 5
50 * ##icon##: none
51 * ##color##: black
52 * ##background##: #EEE
53 )))
54 |##info##|(((
55 * ##timeout##: 5
56 * ##icon##: (i)
57 * ##color##: #28C
58 * ##background##: #DDF
59 )))
60 |##warning##|(((
61 * ##timeout##: 5
62 * ##icon##: /!\
63 * ##color##: 000
64 * ##background##: #FFD
65 )))
66 |##error##|(((
67 * ##timeout##: 10
68 * ##icon##: (!)
69 * ##color##: #900
70 * ##background##: #EDD
71 )))
72 |##inprogress##|(((
73 * ##timeout##: false
74 * ##icon##: spinning
75 * ##color##: #268
76 * ##background##: #EEE
77 )))
78 |##done##|(((
79 * ##timeout##: 2
80 * ##icon##: (v)
81 * ##color##: #090
82 * ##background##: #EFD
83 )))
84
slauriere 6.1 85 = Examples =
Oana Florea 1.1 86
slauriere 8.1 87 {{image reference="notification.png"/}}
Oana Florea 1.1 88
89 {{html}}
90 To see the notification in action just click <a href="#Example" onclick="new XWiki.widgets.Notification('This tutorial is a work in progress.', 'warning');">here</a>.
91 {{/html}}
92
slauriere 5.4 93 Here is the example code of the XWiki widget which displays the ##warning## notification above:
Oana Florea 1.1 94
Guillaume Delhumeau 3.2 95 {{code language="html"}}
Guillaume Delhumeau 3.1 96 To see the notification in action just click <a href="#Example" onclick="new XWiki.widgets.Notification('This tutorial is a work in progress.', 'warning');">here</a>.
Oana Florea 1.1 97 {{/code}}
98
slauriere 6.2 99 Here is a JavaScript snippet for displaying an ##inprogress## notification and replacing it by another one upon request completion or error (snippet taken and adapted from ##AdminGroupSheet##):
slauriere 5.4 100
101 {{code language="javascript"}}
102 var notification = new XWiki.widgets.Notification('Creating group...','inprogress');
103 $.post(createGroupURL, data).done(function() {
104 notification.replace(new XWiki.widgets.Notification('Group created!','done'));
105 }).fail(function() {
106 notification.replace(new XWiki.widgets.Notification('An error occurred','error'));
107 }).always(function() {
108 // ...
109 });
110 {{/code}}
111
Manuel Leduc 13.1 112 {{version since="17.10.9,18.4.0RC1"}}
113 Notification with HTML content
Manuel Leduc 14.1 114
115 {{code language="javascript"}}
116 new XWiki.widgets.Notification('This is <strong>bold</strong>','done', { textHtml: true});
117 {{/code}}
Manuel Leduc 13.1 118 {{/version}}
119
Oana Florea 1.1 120 = Tips =
121
122 Check out the Javascript code:
123
Manuel Smeria 4.2 124 * [[for your wiki instance>>http://localhost:8080/xwiki/bin/skin/resources/uicomponents/widgets/notification.js]]
Guillaume Delhumeau 3.3 125 * from git: {{scm path="xwiki-platform-core/xwiki-platform-web/src/main/webapp/resources/uicomponents/widgets/notification.js"/}}.
Oana Florea 1.1 126
127 Check out the CSS code:
128
Manuel Smeria 4.2 129 * [[for your wiki instance>>http://localhost:8080/xwiki/bin/skin/resources/uicomponents/widgets/notification.css]]
Guillaume Delhumeau 3.3 130 * from git: {{scm path="xwiki-platform-core/xwiki-platform-web/src/main/webapp/resources/uicomponents/widgets/notification.css "/}}.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected