As part of the WordPress Theme Review Team’s plan to curb obtrusive admin notices, the team pushed version 1.0 of its Admin Notices package to the public. The new package provides a standard API for theme authors to display admin notices.

Ari Stathopoulos took over as the packages project lead in late August. Stathopoulos is the primary developer and creator of the highly-rated Kirki customizer framework, which currently has 300,000+ active installs as a plugin. However, the framework is also available as separate modules that theme authors can bundle within their themes.

The Admin Notices package is the third package produced by the team and the first that Stathopoulos has spearheaded.

Adding a basic admin notice in WordPress is relatively easy for most developers. However, handling features such as persistent dismissible actions is more complex. The Admin Notices package handles this out of the box.

Some options for the package include the ability to:

• Set a title and message.
• Select a type that adds in the appropriate UI class (info, success, warning, error).
• Choose which admin screens the notice appears on.
• Limit the message by user capability so that it doesn’t appear for all users.

The above screenshot shows an example of a basic admin notice output for the four available types. The dismiss action is handled by JavaScript and works without reloading the page. Once dismissed, users will no longer see the notice.

“I think the hardest thing about it was deciding how restrictive we wanted it to be,” said Stathopoulos of the challenges building this package. The package restricts theme authors to paragraph, link, bold, and italic elements in version 1.0. It doesn’t leave a lot of room for experimentation, but standardization is the goal. The more elements allowed, the more likely the tool doesn’t solve the team’s problem of keeping admin notices unobtrusive.

User Notifications Are a Complex Problem

WordPress doesn’t provide a formal API for user notifications. However, it does provide a standard set of CSS classes and a hook for attaching notices. The Codex also has some examples of best practices. The lack of a formal API has left theme and plugin authors to their own devices. Users have suffered because of wildly varying implementations and common issues such as non-dismissible advertisements.

Tim Hengeveld proposed a Notification Center API on Trac in 2018. The ticket has a healthy, ongoing discussion and some UI proposals. The proposal is still marked as “Awaiting Review,” and it’s unlikely that it’ll ship anytime sooner than WordPress 5.4 or later.

Currently, many plugins and themes also use admin notices for user onboarding, which is a separate problem in need of a solution. There’s a 4-year-old ticket that discusses WordPress new-user onboarding, but there’s not much movement to solve this problem for plugins and themes.

While the TRT’s package doesn’t tackle all issues associated with user notifications, it does help limit some of the short-term damage.

More Packages in the Works

More packages are currently being built and others are in the planning stages.

The goal of the overall project is to provide theme authors with drop-in modules they can bundle with their themes. The packages are all written in PHP 5.6+ in hopes to push theme authors toward more modern coding practices (relatively speaking, since PHP 7.4 will be released this year). It will also help streamline the review process if more theme authors adopt the packages rather than building everything in-house.

“If we build packages for the most-requested things, we’ll hopefully empower people to build quality themes easier,” explained Stathopoulos. “I think of packages as building blocks for themes.”

Stathopoulos is working on a customizer control for selecting a color with alpha transparency, which could be released as early as next week. It will provide theme users with more control over how their colors appear for themes that implement it.

“After we build the basics I want to focus on packages that would enhance a11y and privacy in themes – two areas where themes are falling short,” he said. “It would help a lot of people, and that is ultimately our goal.”

Theme authors have grown accustomed to installing JavaScript and CSS packages via NPM over the past few years. However, their use of Composer as a PHP dependency manager has lagged. In some part, this could be due to WordPress’ previous reluctance to bump its minimum version of PHP. Many packages available on Packagist, the main Composer repository, do not work with older versions of PHP. WordPress’ recent jump to PHP 5.6+ and plans to move to 7+ in the future may push more theme authors to consider PHP dependency management.

The TRT has a Packagist account and has made all of its packages installable via Composer.

No Requirement to Use Packages Yet

There are no current plans for the TRT to start requiring the use of these packages for specific features, but a few team members have proposed doing so.

“There are valid reasons to enforce the use of these packages, but it can’t happen overnight,” said Stathopoulos. “We want themes in the repository to have some standards, it can not be the wild west. Code quality has to improve. These packages are a way to make life easier for people, and ultimately save time for everyone.”

Stathopoulos is open to theme authors building custom implementations if they can improve upon what the team has built, but he prefers that authors “discuss their ideas in the package repository and submit a pull-request so that the whole community can benefit.”

Getting theme authors involved is one area where the team has struggled. Contributing to the packages could benefit the entire community. “Most people don’t even know about them since they are not listed anywhere,” said Stathopoulos. “Theme Authors currently have to look for them, and in order to look for them someone needs to tell them they exist (which doesn’t happen).” One of the next steps would be getting the packages listed in the TRT’s documentation.

Working together on common theme features could provide a bridge between theme authors and reviewers, allowing them to solve issues together.

Note: The author of this article was involved with the initial theme packages proposal and a developer on its initial package releases.