Feature: rebuild support for custom notices (#9)

Author: JasonTheAdams

README.md

@@ -73,13 +73,17 @@ Parameters:
 
 1. `string $id` - A unique identifier for the notice.
 2. `string|callback $message` - The message to display. This can be a string or a callback that
-   returns a string
+   returns a string. The callback receives an instance of the `AdminNotice` class and an instance of
+   the [NoticeElementProperties](src/DataTransferObjects/NoticeElementProperties.php) class — the
+   latter of which is useful for custom notices.
 
 ```php
 use StellarWP\AdminNotices\AdminNotices;
+use StellarWP\AdminNotices\AdminNotice;
+use \StellarWP\AdminNotices\DataTransferObjects\NoticeElementProperties;
 
 AdminNotices::show('my_notice', 'This is a notice');
-AdminNotices::show('my_notice', function () {
+AdminNotices::show('my_notice', function (AdminNotice $notice, NoticeElementProperties $elements) {
     return 'This is a notice';
 });
 ```
@@ -287,7 +291,7 @@ $notice = AdminNotices::show('my_notice', 'This is a notice')
     });
 ```
 
-## Visual & behavior options
+## Standard Notice Visual & behavior options
 
 ### `autoParagraph($autoParagraph)`, `withoutAutoParagraph()`
 
@@ -316,32 +320,6 @@ $notice = AdminNotices::show('my_notice', 'This is a notice')
     ->withoutAutoParagraph();
 ```
 
-### `withWrapper($with)`, `withoutWrapper()`
-
-**Default:** true
-
-Sets whether the rendered notice should be wrapped in the standard WordPress notice wrapper.
-
-Parameters:
-
-1. `bool $with = true` - Whether to wrap the notice in the standard WordPress notice wrapper
-
-```php
-use StellarWP\AdminNotices\AdminNotices;
-
-// Wrap the notice in the standard WordPress notice wrapper
-$notice = AdminNotices::show('my_notice', 'This is a notice')
-    ->withWrapper();
-
-// Do not wrap the notice in the standard WordPress notice wrapper
-$notice = AdminNotices::show('my_notice', 'This is a notice')
-    ->withWrapper(false);
-
-// Also has an alias for readability
-$notice = AdminNotices::show('my_notice', 'This is a notice')
-    ->withoutWrapper();
-```
-
 ### `urgency($urgency)`
 
 **Default:** 'info'
@@ -446,6 +424,75 @@ $notice = AdminNotices::show('my_notice', 'This is a notice')
     ->notDismissible();
 ```
 
+## 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
+
+```php
+use StellarWP\AdminNotices\AdminNotices;
+
+$notice = AdminNotices::show('my_notice_custom', 'This is a notice')
+    ->custom();
+```
+
+### `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:
+
+1. `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.
+
+```php
+use StellarWP\AdminNotices\AdminNotices;
+
+// Display the notice above the header
+$notice = AdminNotices::show('my_notice_custom', 'This is a notice')
+    ->custom()
+    ->location('above_header');
+```
+
+### 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.
+
+```php
+use StellarWP\AdminNotices\AdminNotices;
+use StellarWP\AdminNotices\AdminNotice;
+use \StellarWP\AdminNotices\DataTransferObjects\NoticeElementProperties;
+
+$renderCallback = function (AdminNotice $notice, NoticeElementProperties $elements) {
+    return "
+        <div>
+            <p>This is a custom notice</p>
+            <button type='button' {$elements->closeAttributes()}>
+                <span class='screen-reader-text'>Dismiss this notice.</span>
+            </button>
+        </div>
+    ";
+};
+
+AdminNotices::show('my_notice', $renderCallback)
+    ->custom();
+```
+
+The [$elements](src/DataTransferObjects/NoticeElementProperties.php) 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')`.
+
 ## Resetting dismissed notices
 
 For dismissible notices, when the user dismisses the notice, it is permanently dismissed. If you

src/Actions/RenderAdminNotice.php

@@ -6,7 +6,9 @@
 namespace StellarWP\AdminNotices\Actions;
 
 use StellarWP\AdminNotices\AdminNotice;
+use StellarWP\AdminNotices\DataTransferObjects\NoticeElementProperties;
 use StellarWP\AdminNotices\Traits\HasNamespace;
+use WP_HTML_Tag_Processor;
 
 /**
  * Renders the admin notice based on the configuration of the notice.
@@ -21,38 +23,51 @@ class RenderAdminNotice
     /**
      * Renders the admin notice
      *
+     * @unreleased custom notices have a completely different render flow
      * @since 1.1.0 added namespacing and notice is passed to the __invoke method
      * @since 1.0.0
      */
     public function __invoke(AdminNotice $notice): string
     {
-        if (!$notice->usesWrapper()) {
-            return $notice->getRenderedContent();
+        $elementProperties = new NoticeElementProperties($notice, $this->namespace);
+        $renderTextOrCallback = $notice->getRenderTextOrCallback();
+
+        if (is_callable($renderTextOrCallback)) {
+            $content = $renderTextOrCallback($notice, $elementProperties);
+        } else {
+            $content = $renderTextOrCallback;
+        }
+
+        if ($notice->isCustom()) {
+            return $this->applyCustomAttributesToContent($content, $notice);
         }
 
         return sprintf(
-            "<div class='%s' data-stellarwp-$this->namespace-notice-id='%s'>%s</div>",
-            esc_attr($this->getWrapperClasses($notice)),
-            $notice->getId(),
-            $notice->getRenderedContent()
+            "<div class='%s' $elementProperties->idAttribute>%s</div>",
+            esc_attr($this->getStandardWrapperClasses($notice)),
+            $notice->shouldAutoParagraph() ? wpautop($content) : $content
         );
     }
 
     /**
      * Generates the classes for the standard WordPress notice wrapper.
      *
+     * @unreleased notice is assumed to be standard only
      * @since 1.1.0 notice is passed instead of accessed as a property
      * @since 1.0.0
      */
-    private function getWrapperClasses(AdminNotice $notice): string
+    private function getStandardWrapperClasses(AdminNotice $notice): string
     {
-        $classes = ['notice', 'notice-' . $notice->getUrgency()];
+        $classes = [
+            'notice',
+            "notice-{$notice->getUrgency()}",
+        ];
 
         if ($notice->isDismissible()) {
             $classes[] = "is-dismissible";
         }
 
-        if ($notice->isInline()) {
+        if ($notice->getLocation() && $notice->getLocation()->isInline()) {
             $classes[] = 'inline';
         }
 
@@ -62,4 +77,26 @@ private function getWrapperClasses(AdminNotice $notice): string
 
         return implode(' ', $classes);
     }
+
+    /**
+     * Apply the needed custom attributes to the content.
+     *
+     * @unreleased
+     */
+    private function applyCustomAttributesToContent(
+        string $content,
+        AdminNotice $notice
+    ): string {
+        $tags = new WP_HTML_Tag_Processor($content);
+
+        $tags->next_tag();
+
+        $tags->set_attribute("data-stellarwp-{$this->namespace}-notice-id", $notice->getId());
+
+        if ($notice->getLocation()) {
+            $tags->set_attribute("data-stellarwp-{$this->namespace}-location", (string)$notice->getLocation());
+        }
+
+        return $tags->__toString();
+    }
 }

src/AdminNotice.php

@@ -9,6 +9,7 @@
 use DateTimeZone;
 use Exception;
 use InvalidArgumentException;
+use StellarWP\AdminNotices\ValueObjects\NoticeLocation;
 use StellarWP\AdminNotices\ValueObjects\NoticeUrgency;
 use StellarWP\AdminNotices\ValueObjects\ScreenCondition;
 use StellarWP\AdminNotices\ValueObjects\UserCapability;
@@ -66,19 +67,19 @@ class AdminNotice
     protected $alternateStyles = false;
 
     /**
-     * @var bool
+     * @var bool Indicates that the notice is customized and not the standard WordPress notice
      */
-    protected $withWrapper = true;
+    protected $custom = false;
 
     /**
      * @var bool
      */
     protected $dismissible = false;
 
     /**
-     * @var bool
+     * @var NoticeLocation|null
      */
-    protected $inline = false;
+    protected $location;
 
     /**
      * @since 1.0.0
@@ -94,6 +95,7 @@ public function __construct(string $id, $renderTextOrCallback)
         $this->id = $id;
         $this->renderTextOrCallback = $renderTextOrCallback;
         $this->urgency = NoticeUrgency::info();
+        $this->location = NoticeLocation::standard();
     }
 
     /**
@@ -317,64 +319,57 @@ public function usesAlternateStyles(): bool
         return $this->alternateStyles;
     }
 
-    /**
-     * Sets the notice to display without the standard WordPress wrapper
-     *
-     * @since 1.0.0
-     */
-    public function withWrapper(bool $withWrapper = true): self
+    public function custom(bool $custom = true): self
     {
-        $this->withWrapper = $withWrapper;
+        $this->custom = $custom;
 
         return $this;
     }
 
-    /**
-     * Sets the notice to display without the standard WordPress wrapper
-     *
-     * @since 1.0.0
-     */
-    public function withoutWrapper(): self
+    public function standard(): self
     {
-        $this->withWrapper = false;
+        $this->custom = false;
 
         return $this;
     }
 
     /**
-     * Returns whether the notice is inline
+     * Sets the notice to be inline
      *
+     * @unreleased removed parameter in favor of new location parameter
      * @since 1.2.0
      */
-    public function isInline(): bool
+    public function inline(): self
     {
-        return $this->inline;
+        $this->location = NoticeLocation::inline();
+
+        return $this;
     }
 
     /**
-     * Sets the notice to be inline
+     * Prevents the notice from being moved from the place it's rendered
      *
-     * @since 1.2.0
+     * @unreleased
      */
-    public function inline(bool $inline = true): self
+    public function inPlace(): self
     {
-        $this->inline = $inline;
+        $this->location = null;
 
         return $this;
     }
 
-    /**
-     * Sets the notice to be not inline
-     *
-     * @since 1.2.0
-     */
-    public function notInline(): self
+    public function location($location): self
     {
-        $this->inline = false;
+        $this->location = $location instanceof NoticeLocation ? $location : new NoticeLocation($location);
 
         return $this;
     }
 
+    public function getLocation(): ?NoticeLocation
+    {
+        return $this->location;
+    }
+
     /**
      * Sets the notice to be dismissible, usable when the notice is displayed in the standard wrapper
      *
@@ -509,14 +504,9 @@ public function getUrgency(): NoticeUrgency
         return $this->urgency;
     }
 
-    /**
-     * Returns whether the notice should be displayed with the standard WordPress wrapper
-     *
-     * @since 1.0.0
-     */
-    public function usesWrapper(): bool
+    public function isCustom(): bool
     {
-        return $this->withWrapper;
+        return $this->custom;
     }
 
     /**