From ea9e42dd644186f4e3e4c94d7023f42ecfb0a9a7 Mon Sep 17 00:00:00 2001 From: Jason Adams Date: Thu, 17 Oct 2024 11:44:47 -0600 Subject: [PATCH 1/4] feature: adds support for alternate styles --- src/Actions/RenderAdminNotice.php | 4 ++ src/AdminNotice.php | 62 +++++++++++++++++ .../Actions/DisplayNoticesInAdminTest.php | 18 ++--- tests/unit/Actions/RenderAdminNoticeTest.php | 10 +-- tests/unit/AdminNoticeTest.php | 67 ++++++++++++++----- tests/unit/NotificationsRegistrarTest.php | 4 +- tests/unit/ValueObjects/NoticeUrgencyTest.php | 14 ++-- .../unit/ValueObjects/ScreenConditionTest.php | 10 +-- 8 files changed, 143 insertions(+), 46 deletions(-) diff --git a/src/Actions/RenderAdminNotice.php b/src/Actions/RenderAdminNotice.php index 86f8e38..37437d9 100644 --- a/src/Actions/RenderAdminNotice.php +++ b/src/Actions/RenderAdminNotice.php @@ -51,6 +51,10 @@ private function getWrapperClasses(): string $classes[] = 'is-dismissible'; } + if ($this->notice->usesAlternateStyles()) { + $classes[] = 'notice-alt'; + } + return implode(' ', $classes); } } diff --git a/src/AdminNotice.php b/src/AdminNotice.php index 954101c..7ec6913 100644 --- a/src/AdminNotice.php +++ b/src/AdminNotice.php @@ -60,11 +60,19 @@ class AdminNotice */ protected $urgency; + /** + * @var bool + */ + protected $alternateStyles = false; + /** * @var bool */ protected $withWrapper = true; + /** + * @var bool + */ protected $dismissible = false; /** @@ -230,26 +238,80 @@ public function urgency($urgency): self return $this; } + /** + * Alias for setting the urgency to info + * + * @since 1.1.0 + */ public function asInfo(): self { return $this->urgency(NoticeUrgency::info()); } + /** + * Alias for setting the urgency to success + * + * @since 1.1.0 + */ public function asSuccess(): self { return $this->urgency(NoticeUrgency::success()); } + /** + * Alias for setting the urgency to warning + * + * @since 1.1.0 + */ public function asWarning(): self { return $this->urgency(NoticeUrgency::warning()); } + /** + * Alias for setting the urgency to error + * + * @since 1.1.0 + */ public function asError(): self { return $this->urgency(NoticeUrgency::error()); } + /** + * Uses the alternate WP notice styles + * + * @unreleased + */ + public function alternateStyles(bool $altStyle = true): self + { + $this->alternateStyles = $altStyle; + + return $this; + } + + /** + * Uses the standard WP notice styles + * + * @unreleased + */ + public function standardStyles(): self + { + $this->alternateStyles = false; + + return $this; + } + + /** + * Returns whether the notice uses the alternate WP notice styles + * + * @unreleased + */ + public function usesAlternateStyles(): bool + { + return $this->alternateStyles; + } + /** * Sets the notice to display without the standard WordPress wrapper * diff --git a/tests/unit/Actions/DisplayNoticesInAdminTest.php b/tests/unit/Actions/DisplayNoticesInAdminTest.php index 1e16b14..32a97e6 100644 --- a/tests/unit/Actions/DisplayNoticesInAdminTest.php +++ b/tests/unit/Actions/DisplayNoticesInAdminTest.php @@ -21,7 +21,7 @@ class DisplayNoticesInAdminTest extends TestCase protected $originalServer; /** - * @unreleased + * @since 1.0.0 */ protected function setUp(): void { @@ -30,7 +30,7 @@ protected function setUp(): void } /** - * @unreleased + * @since 1.0.0 */ protected function tearDown(): void { @@ -39,7 +39,7 @@ protected function tearDown(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldEchoNothingWithNoNotices(): void { @@ -50,7 +50,7 @@ public function testShouldEchoNothingWithNoNotices(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldAcceptMultipleNotices(): void { @@ -66,7 +66,7 @@ public function testShouldAcceptMultipleNotices(): void * @covers ::passesDateLimits * @dataProvider passDateLimitsDataProvider * - * @unreleased + * @since 1.0.0 */ public function testPassesDateLimits(AdminNotice $notice, bool $shouldPass): void { @@ -104,7 +104,7 @@ public function passDateLimitsDataProvider(): array * @dataProvider passWhenCallbackDataProvider * @covers ::passesWhenCallback * - * @unreleased + * @since 1.0.0 */ public function testPassesWhenCallback(AdminNotice $notice, bool $shouldPass): void { @@ -120,7 +120,7 @@ public function testPassesWhenCallback(AdminNotice $notice, bool $shouldPass): v } /** - * @unreleased + * @since 1.0.0 */ public function passWhenCallbackDataProvider(): array { @@ -145,7 +145,7 @@ public function passWhenCallbackDataProvider(): array * @dataProvider passUserCapabilitiesDataProvider * @covers ::passesUserCapabilities * - * @unreleased + * @since 1.0.0 */ public function testPassesUserCapabilities(AdminNotice $notice, bool $shouldPass): void { @@ -241,7 +241,7 @@ public function testShouldPassScreenConditionsWhenConditionMatchesWPScreen(): vo /** * Produces a simple mock with predictable output. * - * @unreleased + * @since 1.0.0 */ private function getSimpleMockNotice($output): AdminNotice { diff --git a/tests/unit/Actions/RenderAdminNoticeTest.php b/tests/unit/Actions/RenderAdminNoticeTest.php index 34e2d0e..aab94ba 100644 --- a/tests/unit/Actions/RenderAdminNoticeTest.php +++ b/tests/unit/Actions/RenderAdminNoticeTest.php @@ -9,7 +9,7 @@ class RenderAdminNoticeTest extends TestCase { /** - * @unreleased + * @since 1.0.0 */ public function testShouldRenderNoticeWithoutWrapper(): void { @@ -25,7 +25,7 @@ public function testShouldRenderNoticeWithoutWrapper(): void /** * Tests the wrapper and that the default urgency is info * - * @unreleased + * @since 1.0.0 */ public function testShouldRenderNoticeInWrapper(): void { @@ -42,7 +42,7 @@ public function testShouldRenderNoticeInWrapper(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldIncludeDismissibleClass(): void { @@ -59,7 +59,7 @@ public function testShouldIncludeDismissibleClass(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldIncludeAutoParagraphs(): void { @@ -77,7 +77,7 @@ public function testShouldIncludeAutoParagraphs(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldRenderCallbackOutput(): void { diff --git a/tests/unit/AdminNoticeTest.php b/tests/unit/AdminNoticeTest.php index 72a5cb2..1670c7b 100644 --- a/tests/unit/AdminNoticeTest.php +++ b/tests/unit/AdminNoticeTest.php @@ -20,7 +20,7 @@ class AdminNoticeTest extends TestCase /** * @covers ::__construct * - * @unreleased + * @since 1.0.0 */ public function testThrowsExceptionWhenRenderIsNotStringOrCallable() { @@ -31,7 +31,7 @@ public function testThrowsExceptionWhenRenderIsNotStringOrCallable() /** * @covers ::ifUserCan * - * @unreleased + * @since 1.0.0 */ public function testIfUserCan(): void { @@ -50,7 +50,7 @@ public function testIfUserCan(): void /** * @covers ::ifUserCan * - * @unreleased + * @since 1.0.0 */ public function testIfUserCanShouldThrowExceptionWhenCapabilityIsNotStringOrArray(): void { @@ -62,7 +62,7 @@ public function testIfUserCanShouldThrowExceptionWhenCapabilityIsNotStringOrArra /** * @covers ::ifUserCan * - * @unreleased + * @since 1.0.0 */ public function testIfUserCanShouldThrowExceptionWhenCapabilityArrayIsMisshaped(): void { @@ -78,7 +78,7 @@ public function testIfUserCanShouldThrowExceptionWhenCapabilityArrayIsMisshaped( * * @dataProvider dateTestProvider * - * @unreleased + * @since 1.0.0 */ public function testAfter($parameter, $assertDate): void { @@ -96,7 +96,7 @@ public function testAfter($parameter, $assertDate): void * * @dataProvider dateTestProvider * - * @unreleased + * @since 1.0.0 */ public function testUntil($parameter, $assertDate): void { @@ -110,7 +110,7 @@ public function testUntil($parameter, $assertDate): void /** * @covers ::between * - * @unreleased + * @since 1.0.0 */ public function testBetween(): void { @@ -136,7 +136,7 @@ public function dateTestProvider(): array * @covers ::when * @covers ::getWhenCallback * - * @unreleased + * @since 1.0.0 */ public function testWhen(): void { @@ -153,7 +153,7 @@ public function testWhen(): void * @covers ::on * @covers ::getOnConditions * - * @unreleased + * @since 1.0.0 */ public function testOn(): void { @@ -169,7 +169,7 @@ public function testOn(): void * @covers ::withoutAutoParagraph * @covers ::shouldAutoParagraph * - * @unreleased + * @since 1.0.0 */ public function testAutoParagraph(): void { @@ -200,7 +200,7 @@ public function testAutoParagraph(): void * @covers ::urgency * @covers ::getUrgency * - * @unreleased + * @since 1.0.0 */ public function testUrgency(): void { @@ -249,7 +249,7 @@ public function testWithWrapper(): void * @covers ::notDismissible * @covers ::isDismissible * - * @unreleased + * @since 1.0.0 */ public function testDismissible(): void { @@ -279,7 +279,7 @@ public function testDismissible(): void /** * @covers ::getRenderTextOrCallback * - * @unreleased + * @since 1.0.0 */ public function testGetRenderTextOrCallback(): void { @@ -296,7 +296,7 @@ public function testGetRenderTextOrCallback(): void /** * @covers ::getRenderedContent * - * @unreleased + * @since 1.0.0 */ public function testRenderedContent(): void { @@ -319,7 +319,7 @@ public function testRenderedContent(): void /** * @covers ::getUserCapabilities * - * @unreleased + * @since 1.0.0 */ public function testGetUserCapabilities(): void { @@ -337,7 +337,7 @@ public function testGetUserCapabilities(): void /** * @covers ::getAfterDate * - * @unreleased + * @since 1.0.0 */ public function testGetAfterDate(): void { @@ -354,7 +354,7 @@ public function testGetAfterDate(): void /** * @covers ::getUntilDate * - * @unreleased + * @since 1.0.0 */ public function testGetUntilDate(): void { @@ -371,7 +371,7 @@ public function testGetUntilDate(): void /** * @covers ::getWhenCallback * - * @unreleased + * @since 1.0.0 */ public function testGetWhenCallback(): void { @@ -384,4 +384,35 @@ public function testGetWhenCallback(): void $notice->when($callback); $this->assertSame($callback, $notice->getWhenCallback()); } + + /** + * @covers ::alternateStyles + * @covers ::standardStyles + * @covers ::usesAlternateStyles + */ + public function testAlternateStyles(): void + { + $notice = new AdminNotice('test_id', 'test'); + + // Defaults to false + $this->assertFalse($notice->usesAlternateStyles()); + + // Method can be set to true + $self = $notice->alternateStyles(); + $this->assertTrue($notice->usesAlternateStyles()); + $this->assertSame($notice, $self); + + // Method can be explicitly set to false + $notice->alternateStyles(false); + $this->assertFalse($notice->usesAlternateStyles()); + + // Method can be set to true + $notice->alternateStyles(true); + $this->assertTrue($notice->usesAlternateStyles()); + + // standardStyles is an alias for alternateStyles(false) + $self = $notice->standardStyles(); + $this->assertFalse($notice->usesAlternateStyles()); + $this->assertSame($notice, $self); + } } diff --git a/tests/unit/NotificationsRegistrarTest.php b/tests/unit/NotificationsRegistrarTest.php index be13956..c3609ac 100644 --- a/tests/unit/NotificationsRegistrarTest.php +++ b/tests/unit/NotificationsRegistrarTest.php @@ -15,7 +15,7 @@ class NotificationsRegistrarTest extends TestCase * @covers ::registerNotice * @covers ::getNotices * - * @unreleased + * @since 1.0.0 */ public function testRegisterNotice(): void { @@ -29,7 +29,7 @@ public function testRegisterNotice(): void /** * @covers ::unregisterNotice * - * @unreleased + * @since 1.0.0 */ public function testUnregisterNotice(): void { diff --git a/tests/unit/ValueObjects/NoticeUrgencyTest.php b/tests/unit/ValueObjects/NoticeUrgencyTest.php index e575dd7..f748f53 100644 --- a/tests/unit/ValueObjects/NoticeUrgencyTest.php +++ b/tests/unit/ValueObjects/NoticeUrgencyTest.php @@ -16,7 +16,7 @@ class NoticeUrgencyTest extends TestCase { /** * @covers ::info - * @unreleased + * @since 1.0.0 */ public function testInfo(): void { @@ -25,7 +25,7 @@ public function testInfo(): void /** * @covers ::warning - * @unreleased + * @since 1.0.0 */ public function testWarning(): void { @@ -34,7 +34,7 @@ public function testWarning(): void /** * @covers ::error - * @unreleased + * @since 1.0.0 */ public function testError(): void { @@ -43,7 +43,7 @@ public function testError(): void /** * @covers ::success - * @unreleased + * @since 1.0.0 */ public function testSuccess(): void { @@ -52,7 +52,7 @@ public function testSuccess(): void /** * @covers ::__toString - * @unreleased + * @since 1.0.0 */ public function testToString(): void { @@ -63,7 +63,7 @@ public function testToString(): void * @covers ::__construct * @dataProvider constructorTestDataProvider * - * @unreleased + * @since 1.0.0 */ public function testConstructorValidation($value, $shouldPass): void { @@ -76,7 +76,7 @@ public function testConstructorValidation($value, $shouldPass): void } /** - * @unreleased + * @since 1.0.0 */ public function constructorTestDataProvider(): array { diff --git a/tests/unit/ValueObjects/ScreenConditionTest.php b/tests/unit/ValueObjects/ScreenConditionTest.php index 248a939..da8602b 100644 --- a/tests/unit/ValueObjects/ScreenConditionTest.php +++ b/tests/unit/ValueObjects/ScreenConditionTest.php @@ -20,7 +20,7 @@ class ScreenConditionTest extends TestCase /** * @covers ::isRegex * - * @unreleased + * @since 1.0.0 */ public function testIsRegex(): void { @@ -44,7 +44,7 @@ public function testIsRegex(): void /** * @covers ::getCondition * - * @unreleased + * @since 1.0.0 */ public function testGetCondition(): void { @@ -53,7 +53,7 @@ public function testGetCondition(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldThrowExceptionWithNonStringOrArray(): void { @@ -62,7 +62,7 @@ public function testShouldThrowExceptionWithNonStringOrArray(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldThrowExceptionWithNonAssociativeArray(): void { @@ -71,7 +71,7 @@ public function testShouldThrowExceptionWithNonAssociativeArray(): void } /** - * @unreleased + * @since 1.0.0 */ public function testShouldThrowExceptionForInvalidWPScreenProperties(): void { From 82678f285b9e3e13ebc4e995de6075ec0bc1178f Mon Sep 17 00:00:00 2001 From: Jason Adams Date: Thu, 17 Oct 2024 11:57:30 -0600 Subject: [PATCH 2/4] chore: adds methods to readme --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/README.md b/README.md index 31bedbe..da8c7c1 100644 --- a/README.md +++ b/README.md @@ -366,6 +366,58 @@ $notice = AdminNotices::show('my_notice', 'This is a notice') ->urgency($urgency); ``` +### `alternateStyles($useAlternate)`, `standardStyles()` + +**Default:** false + +Sets whether the notice should use the alternate WordPress notice styles. **Only works when the +wrapper is enabled.** + +Parameters: + +1. `bool $useAlternate = true` - Whether the notice should use the alternate WordPress notice + styles + +```php +use StellarWP\AdminNotices\AdminNotices; + +// Use the alternate WordPress notice styles +$notice = AdminNotices::show('my_notice', 'This is a notice') + ->alternateStyles(); + +// Use the standard WordPress notice styles, only necessary to revert back +$notice = AdminNotices::show('my_notice', 'This is a notice') + ->alternateStyles() + ->standardStyles(); +``` + +### `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: + +1. `bool $inline = true` - Whether the notice should be displayed inline + +```php +use StellarWP\AdminNotices\AdminNotices; + +// Display the notice inline +$notice = AdminNotices::show('my_notice', 'This is a notice') + ->inline(); + +// Display the notice in the standard location +$notice = AdminNotices::show('my_notice', 'This is a notice') + ->inline(false); + +// Also has an alias for readability +$notice = AdminNotices::show('my_notice', 'This is a notice') + ->notInline(); +``` + ### `dismissible($dismissible)`, `notDismissible()` **Default:** false From f8166f55d5a8b31a9b2f290944a3540933cecc66 Mon Sep 17 00:00:00 2001 From: Jason Adams Date: Thu, 17 Oct 2024 12:17:44 -0600 Subject: [PATCH 3/4] fix: updated RenderAdminNotice to use local notice --- src/Actions/RenderAdminNotice.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Actions/RenderAdminNotice.php b/src/Actions/RenderAdminNotice.php index c3f3224..21a6efc 100644 --- a/src/Actions/RenderAdminNotice.php +++ b/src/Actions/RenderAdminNotice.php @@ -56,7 +56,7 @@ private function getWrapperClasses(AdminNotice $notice): string $classes[] = 'inline'; } - if ($this->notice->usesAlternateStyles()) { + if ($notice->usesAlternateStyles()) { $classes[] = 'notice-alt'; } From 02800df9c4367589cf38e83e0a5859445d208a95 Mon Sep 17 00:00:00 2001 From: Jason Adams Date: Thu, 17 Oct 2024 12:26:41 -0600 Subject: [PATCH 4/4] test: add missing unreleased tag --- tests/unit/AdminNoticeTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/unit/AdminNoticeTest.php b/tests/unit/AdminNoticeTest.php index 6c9ed8d..4c7fb3e 100644 --- a/tests/unit/AdminNoticeTest.php +++ b/tests/unit/AdminNoticeTest.php @@ -421,6 +421,8 @@ public function testGetWhenCallback(): void * @covers ::alternateStyles * @covers ::standardStyles * @covers ::usesAlternateStyles + * + * @unreleased */ public function testAlternateStyles(): void {