Regardless of your level of experience with WordPress, everyone is familiar with seeing the messages that display whenever an action has completed within the dashboard:
- We have success messages for when something has completed, ahem, successfully,
- We have notification messages which are neutral pieces of information that give a heads up something has happened,
- And we have error messages that let us know that something has gone wrong.
For anyone that’s read past articles, you know that when it comes to introducing functionality into the WordPress dashboard, I firmly believe that the work we do should look as native as possible. That is to say that I am not a fan of custom styles, custom controls, or extraordinary styles to give your theme or plugin that “extra edge.”
And for those who are familiar with the Settings API and/or the Options API, then you’re likely familiar with introducing new sections, settings, controls, and options, but what about error messages?
Generally speaking, success messages and notification messages are reasonably easy to come by, but let’s say that you need to validate some piece of information that’s coming into the server and return an error if it fails.
Display Error Messages in WordPress
As with most things, things like this are usually best demonstrated through a practical example. Luckily, there’s no too much to setup before we take a look at how to do it.
So let’s assume the following:
- We have a meta box on the post dashboard
- The meta box contains an input box
- When the post is saved, the input box cannot be empty (I know, that’s a bit extreme, but it’ll demonstrate the point)
- If the input box is empty, then we’ll display an error message
Easy enough, but in order to save time, I’m going to assume you’re familiar with the add_meta_boxes
action, the add_meta_box
function, the save_post
hook and how to validate data from within the hooked function.
In this case, we’re going to be making sure that the data coming in from the meta box input is not empty. If it is, then we’ll display a native WordPress error message.
To that end, let’s assume that the input box has the name
attribute of acme-input-field
and it can be accessed via the $_POST
collection by retrieving it as $_POST['acme-input-field']
.
From there, let’s do something like the following:
Notice that in the above function, the majority of the work is checking that the user has permission to save the data and the the incoming information is not empty. If it is empty, then we make a call to add_settings_error
.
According to the Codex, this function:
Use this to show messages to users about settings validation problems, missing settings or anything else.
This is exactly what we’re aiming for when wanting to displaying a natively styled error message, isn’t it?
Lastly, if you’re curious about the second parameter and as to why I left it an empty string, it’s because the default parameter is an empty string, but is used for this:
Slug-name to identify the error. Used as part of ‘id’ attribute in HTML output. A prefix of ‘setting-error-‘ will be added to the string in $code and assigned to the ‘id’ attribute of the outermost <div> for this error.
For all intents an purposes of this particular example, this wasn’t needed, but if you’re looking to gain access to this message via CSS or JavaScript, or are looking to make sure every element has proper semantics, then I highly recommend using it.
Leave a Reply
You must be logged in to post a comment.