autoptimize / classes / external / php / persist-admin-notices-dismissal / README.md

README.md in Autoptimize trunk, at classes/external/php/persist-admin-notices-dismissal/README.md

118 lines 4.5 KB

Raw Download Zip

1	# Persist Admin notice Dismissals
2	[](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal![Latest Stable Version](https://poser.pugx.org/collizo4sky/persist-admin-notices-dismissal/v/stable)](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal)
3	[](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal![Total Downloads](https://poser.pugx.org/collizo4sky/persist-admin-notices-dismissal/downloads)](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal](https://packagist.org/packages/collizo4sky/persist-admin-notices-dismissal)
4
5	Simple framework library that persists the dismissal of admin notices across pages in WordPress dashboard.
6
7	## Installation
8
9	Run `composer require collizo4sky/persist-admin-notices-dismissal`
10
11	Alternatively, clone or download this repo into the `vendor/` folder in your plugin, and include/require the `persist-admin-notices-dismissal.php` file like so
12
13	```php
14	require __DIR__ . '/vendor/persist-admin-notices-dismissal/persist-admin-notices-dismissal.php';
15	add_action( 'admin_init', array( 'PAnD', 'init' ) );
16	```
17
18	or let Composer's autoloader do the work.
19
20	## How to Use
21	Firstly, install and activate this library within a plugin.
22
23	Say you have the following markup as your admin notice,
24
25
26	```php
27	function sample_admin_notice__success() {
28	?>
29	<div class="updated notice notice-success is-dismissible">
30	<p><?php _e( 'Done!', 'sample-text-domain' ); ?></p>
31	</div>
32	<?php
33	}
34	add_action( 'admin_notices', 'sample_admin_notice__success' );
35	```
36
37	To make it hidden forever when dismissed, add the following data attribute `data-dismissible="disable-done-notice-forever"` to the div markup like so:
38
39
40	```php
41	function sample_admin_notice__success() {
42	if ( ! PAnD::is_admin_notice_active( 'disable-done-notice-forever' ) ) {
43	return;
44	}
45
46	?>
47	<div data-dismissible="disable-done-notice-forever" class="updated notice notice-success is-dismissible">
48	<p><?php _e( 'Done!', 'sample-text-domain' ); ?></p>
49	</div>
50	<?php
51	}
52	add_action( 'admin_init', array( 'PAnD', 'init' ) );
53	add_action( 'admin_notices', 'sample_admin_notice__success' );
54	```
55
56	## Autoloaders
57	When using the framework with an autoloader you must also load the class outside of the `admin_notices` or `network_admin_notices` hooks. The reason is that these hooks come after the `admin_enqueue_script` hook that loads the javascript.
58
59	Just add the following in your main plugin file.
60
61	```php
62	add_action( 'admin_init', array( 'PAnD', 'init' ) );
63	```
64
65	#### Usage Instructions and Examples
66	If you have two notices displayed when certain actions are triggered; firstly, choose a string to uniquely identify them, e.g. `notice-one` and `notice-two`
67
68	To make the first notice never appear once dismissed, its `data-dismissible` attribute will be `data-dismissible="notice-one-forever"` where `notice-one` is its unique identifier and `forever` is the dismissal time period.
69
70	To make the second notice only hidden for 2 days, its `data-dismissible` attribute will be `data-dismissible="notice-two-2"` where `notice-two` is its unique identifier and the `2`, the number of days it will be hidden is the dismissal time period.
71
72	You must append the dismissal time period to the end of your unique identifier with a hyphen (`-`) and this value must be an integer. The only exception is the string `forever`.
73
74	To actually make the dismissed admin notice not to appear, use the `is_admin_notice_active()` function like so:
75
76
77	```php
78	function sample_admin_notice__success1() {
79	if ( ! PAnD::is_admin_notice_active( 'notice-one-forever' ) ) {
80	return;
81	}
82
83	?>
84	<div data-dismissible="notice-one-forever" class="updated notice notice-success is-dismissible">
85	<p><?php _e( 'Done 1!', 'sample-text-domain' ); ?></p>
86	</div>
87	<?php
88	}
89
90	function sample_admin_notice__success2() {
91	if ( ! PAnD::is_admin_notice_active( 'notice-two-2' ) ) {
92	return;
93	}
94
95	?>
96	<div data-dismissible="notice-two-2" class="updated notice notice-success is-dismissible">
97	<p><?php _e( 'Done 2!', 'sample-text-domain' ); ?></p>
98	</div>
99	<?php
100	}
101
102	add_action( 'admin_init', array( 'PAnD', 'init' ) );
103	add_action( 'admin_notices', 'sample_admin_notice__success1' );
104	add_action( 'admin_notices', 'sample_admin_notice__success2' );
105	```
106
107	You should be a good developer and add the following to your `uninstall.php` file so that we can clean up after ourselves and not leave unnecessary stuff in the options table.
108
109	```php
110	global $wpdb;
111	$table = is_multisite() ? $wpdb->base_prefix . 'sitemeta' : $wpdb->base_prefix . 'options';
112	$column = is_multisite() ? 'meta_key' : 'option_name';
113	$delete_string = 'DELETE FROM ' . $table . ' WHERE ' . $column . ' LIKE %s LIMIT 1000';
114	$wpdb->query( $wpdb->prepare( $delete_string, array( '%pand-%' ) ) );
115	```
116
117	Cool beans. Isn't it?
118