This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.
Consider the error severity, then choose the right message type and send it to the right people.
Look at the severity of the error. If it is severe, show it in a banner. Who needs to know about it? Typically the logged-in user only, not everybody. Each visual element in the Magnolia UI is designed to carry a specific type of message. Every message type has characteristics you should be familiar with so that you can choose the right vehicle.
Validate user input to avoid errors
Validate input and check preconditions early on.
- Validate user input directly in the form or UI. Use an inline message to show problems. You may also show warnings.
- Use validators to determine if all preconditions for a task are met.
- If preconditions are not met, use an inline message to signal the problem: "Please provide a valid email address."
- It's not OK to run a task to just see how it fails because some preconditions were not met.
Show banners for severe errors
Banner is the best choice for severe errors because the system stores message and it can be forwarded and analyzed further.
|Severity||Message type||Send to|
|Critical errors (exceptions)||Banner||Logged-in user|
|Severe errors (exceptions that leave the app in a bad state)||Banner||Logged-in user, administrator|
|Security breaches or similar||Banner||Administrator|
Show alerts when it's enough that the user sees the error
Show an alert when the user must see the error. It's a good idea to show an alert also if your app must abort the task or the task needs input from the user before it can continue.
Alert captures the user's attention
Notification is too easy to miss.
Never use a notification to signal errors. Notifications are too easy to miss. Instead, put more effort on validation before kicking off the action. You should only use a notification to confirm that an action was aborted. For example, if the user uploads a file and decides to cancel the running upload, it's OK to show a notification to confirm that the upload was aborted. The user can also determine that the upload was cancelled by looking at the UI: no progress bar anymore but also no uploaded files.
Who needs to know?
Don't broadcast errors to all users. Error messages are typically only relevant for users who caused it. Only the current user can fix the error or recover from it. Other users consider such messages noise. If the end user cannot correct the error then you may need to send it also to the superuser or administrator group.
How much detail?
Error messages must be detailed so they can be properly dealt with. If all you do is throw a single type of exception to signal errors in code, you are probably on the wrong track. Exceptions are also pretty bad performance-wise: raising them needs a lot of processing power and memory.