WMessageBox
WMessageBox is a component for containing and highlighting feedback messages including WValidationErrors.
- Using WMessageBox
- Creating a WMessageBox
- Placing a message box
- HTML output
- Appearance
- Related Components
- Further information
The most common use case is to not use WMessageBox directly but to add a WMessages component to a UI. This is then used to display WMessageBox components if any messages are to be shown to the user.
WMessages messages = new WMessages();
add(messages);
//.. then add messages as required.A WMessageBox may be created and used directly however. This is particularly handy for messages which are not output as a result of of an Action; for example information or success messages.
// a success box
WMessageBox msgBox = new WMessageBox(WMessageBox.SUCCESS);A WMessageBox may contain a default message in the constructor:
WMessageBox msgBox = new WMessageBox(WMessageBox.SUCCESS,
"Congratulations, you made it to the end");Messages are usually HTML escaped but may also be unescaped:
WMessageBox msgBox = new WMessageBox(WMessageBox.SUCCESS, false,
"Congratulations, you made it to «The End»");A Message is added using addMessage. Messages are HTML escaped by default but may be unescaped.
// Given WMessageBox box:
// a HTML escaped message
box.addMessage("Some message.");
// an unescaped message
box.addMessage(false, "This has a <strong>BOLD</strong> bit.");Messages are removed using removeMessage (funnily enough) but one has to get the message index from the list of messages. All messages may be removed using clearMessages.
// Given WMessageBox box with `n` (> 0) messages
// remove the first message
box.removeMessage(0);
// remove all messages
box.clearMessages();It is possible that a message may become obsolete due to an AJAX transaction. An error message, for example, may need to be deleted if an ajax transaction has rectified the error. WMessageBox may be a target for WAjaxControl and therefore the messages may be updated in the same transaction.
Generally a message to a user should be in context of the task to which it applies. Error messages should be placed before any components which are in an error state and WValidationErrors should be placed before any validated form content.
One would expect a message box containing information pertinent to completing a process to be provided before the start of the process. So, as a rule of thumb: put messages above the content to which they refer.
WMessageBox outputs a section element and must not be placed in WComponents which must only contain phrasing content.
The message level is set using the WMessageBox Type and in turn determines the appearance and fallback title of the WMessageBox. The WMessageBox Type may be set directly. If the WMessageBox is a display artefact of WMessages then the Type is determined by the type of messages added to the WMessages component.
Only one Type of message may be displayed in a WMessageBox but several WMessageBoxes may be displayed in a single view. Available settings are:
-
SUCCESS
-
INFO
-
WARN
-
ERROR(and WValidationErrors)
The WMessageBox title can be set for any given instance of WMessageBox in a particular UI context. The default theme does not display the title in the viewport but it is still present in the accessibility tree. If a title is not set a default title is used. These are based on the WMessageBox type:
-
SUCCESS: "Success" -
INFO: "Information" -
WARN: "Warning" -
ERROR(and WValidationErrors): "An error has occurred"
The WMessageBox title is presented in a span within the WMessageBox's h1 element. Themes may choose if they wish to expose the title in the viewport.
// with WMessagebox msgBox
msgBox.setTitle("Now read this!");WMessageBox may be hidden (and shown) by a WSubordinateControl allowing messages to be removed if they are no longer relevant to the user without a need for a transaction with the server (via Ajax or otherwise).