Handling admin notices in WordPress plugins

I find admin notices are a pain. Every time I write a plugin there comes a point where I think “I’ll just add in some notices to help the user” – and two hours later…

I kept thinking, “This should be so much easier”, so finally I sat down and wrote a class that I can use in any plugin to handle pretty much every admin notice scenario I could think of. It’s available on Github for download with how-to explanatory info and examples.

Why use the class?

The built-in WordPress functionality works fine, and just adding a notice is pretty simple. Handling dismissals properly though, that’s not so hot. You can make a notice “dismissable” easily enough, but all that does is add a cross icon that removes the notice via javascript. What it doesn’t do is store in the database that the user has dismissed the notice – so unless you add in code to handle it, the notice will pop right back up when the page is reloaded.

Even one-time notices – notices that are automatically dismissed once viewed – aren’t entirely straightforward. It all needs some coding.

Hopefully, using the Admin Notice Manager class makes everything a whole lot simpler.

Summary features

Full info is over at the Github readme, but the key features are:

• One-off and Persistent notices. One-off notices are dismissed automatically when viewed. Persistent notices must be dismissed – either by the user or programmatically.
• Added and Opt out notices. Added notices are stored in usermeta against the users that should see them – and are then removed on dismissal. Opt out notices are defined in the plugin and it’s the dismissals that are stored in usermeta.
• Easily defined dismiss buttons or links for use within a notice.
• Simple-to-create redirect links within a notice that both dismiss and redirect.
• For each notice, options to define who can see the notice and where.
• Notice-specific and button-specific actions fired on dismissal so your plugin can do something when a user dismisses a notice.
• Graceful fallback for non-JS.

How to use

You’ll need to download the files from Github, include them in your plugin and initialize the class – as explained here.

Then you can use the class methods from anywhere within your plugin. The two critical ones are add_notice( $args ) and add_opt_out_notice( $args ). The array of arguments is similar for both, although there are some minor differences. More detail is available in the readme (in particular the defaults), but in summary the arguments available are:

• id string Unique id for this notice.
• message string Message to be displayed.
• wrap_tag string Tag to wrap message in.
• type string One of ‘success’, ‘error’, warning’, ‘info’.
• user_ids array Array of user ids or user roles for whom message should be displayed.
• screen_ids array|string Array of screen ids on which message should be displayed.
• post_ids array Array of post ids on which message should be displayed.
• persistent string True for persistent, false for one-time.
• dismissable bool Whether notice is dismissable.
• no_js_dismissable bool Whether to give option to dismiss notice if no js.
• dismiss_all bool Whether to delete notice for all users or just the user that has dismissed the notice.

Feedback and suggestions

I’ve used this class a little, but it’s new and relatively untested. Suggestions or feedback are very welcome, either in the comments below,  through the contact form, or by filing an issue on Github.