Download the PHP package stellarwp/admin-notices without Composer
On this page you can find all versions of the php package stellarwp/admin-notices. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download stellarwp/admin-notices
More information about stellarwp/admin-notices
Files in stellarwp/admin-notices
Package admin-notices
Short Description A handy package for easily displaying admin notices in WordPress with simple to complex visibility conditions
License MIT
Informations about the package admin-notices
Introduction
Displaying notices within the WordPress admin is a highly common need in plugins. Displaying notices is not difficult, but it gets tedious when wanting to conditionally display notices based on conditions such as user capability, the current screen, date range, and so forth.
This library is intended to provide a simple, readable way for developers to conditionally display standard or highly customized notices within the WordPress admin.
How to use
Installation
It's recommended that you install Admin Notices as a project dependency via Composer:
We actually recommend that this library gets included in your project using Strauss.
Luckily, adding Strauss to your
composer.json
is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.
Configuration & Initialization
The AdminNotices
class can be used to configure the library to work within your system and avoid
conflicts with other plugins. Here's an example of what typical setup may look like:
The initialize
method accepts two arguments:
- A unique identifier for your plugin. This is used to avoid conflicts with other plugins.
- The URL to the library's assets directory. This is used to enqueue the necessary JS files.
Service Containers
It is not required to use a service container with this library, however if you are using one and
want it to fit within your system, you can connect your container, which must implement the
Psr\Container\ContainerInterface
interface.
Once connected, your container must provide a concrete instance of the
StellarWP\AdminNotices\Contracts\NotificationsRegistrarInterface
interface. You can either bind
the StellarWP\AdminNotices\NotificationsRegistrar
class to the interface, or create your own class
that implements the interface.
Displaying Notices
All notices are displayed using the StellarWP\AdminNotices\AdminNotices
facade. There are a few
methods to manage notices:
addNotice($id, $message)
Adds a notice to the queue to be displayed in the standard WordPress admin notice area.
Parameters:
string $id
- A unique identifier for the notice.string|callback $message
- The message to display. This can be a string or a callback that returns a string. The callback receives an instance of theAdminNotice
class and an instance of the NoticeElementProperties class — the latter of which is useful for custom notices.
removeNotice($id)
Removes a notice from the queue.
Parameters:
string $id
- The unique identifier for the notice to remove
render(AdminNotice $notice)
Immediately renders the notice to the screen. This is useful if you want to display the notice in a non-standard location.
Parameters:
AdminNotice $notice
- The notice to render
Notice Conditions
At the core of this library is the AdminNotice
class. This class is used to define the notice and
its conditions. When the AdminNotices::show()
method is used, it returns a new instance of the
AdminNotice
class to be fluently configured. For example:
on(...$screen)
Sets the screen where the notice should be displayed. This can be one of:
- A string representing a portion of the URL
- A regex delimited with ~ to compare against the URL (e.g.
~edit\.php~i
) - An associative array that is compared against the
WP_Screen
object (e.g.['id' => 'edit-post']
)
If multiple screen conditions are provided, the notice will be displayed if any of the conditions are met.
Parameters:
string|array $screen
- The screen to display the notice on
ifUserCan(...$capability)
Sets the capability required to view the notice. This can be a single capability or an array of
capabilities. Under the hood, current_user_can
is used to check the capability. Each capability
can be one of:
- A string representing a capability
- An array where the elements are spread to the
current_user_can
function - An instance of the
StellarWP\AdminNotices\ValueObjects\UserCapability
class
If multiple capabilities are provided, the notice will be displayed if the user has any of the capabilities.
Parameters:
string|array|UserCapability $capability
- The capability required to view the notice
after($date)
Sets the date after which the notice should be displayed.
Parameters:
string $date
- The date after which the notice should be displayed.
until($date)
Sets the date until which the notice should be displayed.
Parameters:
string $date
- The date until which the notice should be displayed.
between($start, $end)
Sets the date range during which the notice should be displayed. The dates can be the same string,
int, or DateTime object as the after
and until
methods.
Parameters:
string $start
- The start date of the range.string $end
- The end date of the range.
when($callback)
Sets a custom condition for when the notice should be displayed. The callback should return a boolean value.
Parameters:
callable $callback
- The callback that returns a boolean value
Standard Notice Visual & behavior options
autoParagraph($autoParagraph)
, withoutAutoParagraph()
Default: false
Sets whether the notice message should be automatically wrapped in a paragraph tag. It uses wpautop under the hood.
Parameters:
bool $autoParagraph = true
- Whether to automatically wrap the message in a paragraph tag
urgency($urgency)
Default: 'info'
Sets the urgency of the notice. This is used to determine the color of the notice. Only works when the wrapper is enabled.
Parameters:
string $urgency
- The urgency of the notice. Can be 'info', 'success', 'warning', or 'error'
alternateStyles($useAlternate)
, standardStyles()
Default: false
Sets whether the notice should use the alternate WordPress notice styles. Only works when the wrapper is enabled.
Parameters:
bool $useAlternate = true
- Whether the notice should use the alternate WordPress notice styles
inline($inline)
, notInline()
Default: false
Sets whether the notice should be displayed in the WP "inline" location, at the top of the admin page. Only works when the wrapper is enabled.
Parameters:
bool $inline = true
- Whether the notice should be displayed inline
dismissible($dismissible)
, notDismissible()
Default: false
Sets whether the notice should be dismissible. This adds a dismiss button to the notice. When the user dismisses the notice, it is permanently dismissed. This is stored in the user's preference meta. Only works when the wrapper is enabled.
Parameters:
bool $dismissible = true
- Whether the notice should be dismissible
Custom Notices
Sometimes you want to display a notice, but you want to completely style it yourself. This is possible and pretty straightforward to do.
Start by using the custom
method on the notice. This will disable all standard visual and behavior
location()
Default: 'standard'
Sets the location in one of the standard WordPress notice locations. By default, the notice will be displayed in the standard location.
Parameters:
string $location
- The location to display the notice. Can be 'standard', 'above_header', ' below_header', or 'inline'. Note that 'standard' and 'below_header' are the same location.
Dismissing
The dismissible
method is not available for custom notices. If you want to add a dismiss button,
you will need to do so manually. Fortunately, there is a simple way to do this.
The $elements object provides a
customCloserAttributes
method that returns the necessary attributes to be place on the dismiss
button. This method will add the necessary attributes to dismiss the notice when clicked. This will
permanently dismiss the notice, and fade out the notice, similar to the standard WordPress
dismissible notices.
If you want the notice to be marked as dismissed, but not fade out, you can pass "clear" to the
customerCloserAttributes
method: e.g. $elements->customCloserAttributes('clear')
.
Custom scripts & styles
Often times, especially for custom notices, you may want to enqueue custom scripts and styles,
however they should only be enqueued when the notice is displayed. This can be done by using the
enqueueScript
and enqueueStyle
methods on the notice.
enqueueScript($src, $deps = [], $ver = false, $args = [])
Enqueues a script to be loaded when the notice is displayed, following the same parameters as
wp_enqueue_script
. The only difference is that the loading strategy is "defer" by default.
enqueueStyle($src, $deps = [], $ver = false, $media = 'all')
Enqueues a style to be loaded when the notice is displayed, following the same parameters as
wp_enqueue_style
.
Resetting dismissed notices
For dismissible notices, when the user dismisses the notice, it is permanently dismissed. If you want to reset the dismissed notice(s), there are a couple methods available.
resetNoticeForUser($notificationId, $userId)
Reset a specific notification for a user.
Parameters:
string $notificationId
- The unique identifier for the noticeint $userId
- The user ID to reset the notice for
resetAllNoticesForUser($userId)
Reset all dismissed notices for a user.
Parameters:
int $userId
- The user ID to reset all notices for