|
| 1 | +# WordPress Dismissible Notices Handler |
| 2 | + |
| 3 | +[](https://scrutinizer-ci.com/g/julien731/WP-Dismissible-Notices-Handler/?branch=master) |
| 4 | + |
| 5 | +Since version 4.2, WordPress has a built-in mechanism for handling dismissible admin notices. While this mechanism handles dismissing notices, the dismissal isn't persistent. This means that a user would see the notice on every page load, even though he or she dismissed the notice already. |
| 6 | + |
| 7 | +What the Dismissible Notices Handler (DNH) library does is handle the persistent part of dismissing admin notices. |
| 8 | + |
| 9 | +## How It Works |
| 10 | + |
| 11 | +The DNH library is extremely simple to use and yet has a couple of advanced options. |
| 12 | + |
| 13 | +The basics of it is to register a new admin notice. You really need 3 things for registering a notice: |
| 14 | + |
| 15 | +- a unique ID that will identify the notice (you will be warned in case of ID conflicts) |
| 16 | +- a notice type |
| 17 | +- a message to display in the notice |
| 18 | + |
| 19 | +There is a handy helper function available for notice registration: `dnh_register_notice()` |
| 20 | + |
| 21 | +This function takes 3 parameters: |
| 22 | + |
| 23 | +- `$id` *(string)*: the unique ID of the notice |
| 24 | +- `$type` *(string)*: the type of notice you want to display. Currently it can be `error` for an error notice or `updated` for a success/update notice |
| 25 | +- `$content` *(string)*: the content of the admin notice |
| 26 | +- `$args` *(array)*: additional parameters that can be passed to the notice handler (see below) |
| 27 | + |
| 28 | +#### Installation |
| 29 | + |
| 30 | +The simpest way to use DNH is to add it as a Composer dependency: |
| 31 | + |
| 32 | +``` |
| 33 | +composer require julien731/wp-dismissible-notices-handler |
| 34 | +``` |
| 35 | + |
| 36 | +### Example |
| 37 | + |
| 38 | +Registering an admin notice would look like that: |
| 39 | + |
| 40 | +``` |
| 41 | +dnh_register_notice( 'my_notice', 'updated', __( 'This is my notice' ) ); |
| 42 | +``` |
| 43 | + |
| 44 | +## Advanced Parameters |
| 45 | + |
| 46 | +The function takes an array of optional parameters allowing more control over the notices and how they're dismissed. Only 2 parameters are available so far but hopefully more will be coming soon. |
| 47 | + |
| 48 | +Hereafter is the list of available parameters to be passed in the `$args` array. Please note that the `$args` parameter is optional. |
| 49 | + |
| 50 | +| Parameter | Possible Value(s) | Default | Description | |
| 51 | +|-----------|--------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 52 | +| scope | user, global | user | Whether the notice should be dismissed for the current user only or globally on the site. A notice dismissed for a user will still show up for other users, while a notice dismissed globally will not be displayed anymore after being dismissed once. | |
| 53 | +| cap | Any WordPress capability | | If not empty, the handler will check if the current user has the specified before displaying the notice. | |
| 54 | +| class | string | | Additional class to add to the notice wrapper | | | | |
0 commit comments