Merge pull request #17 from tattersoftware/v3

Refactor

Author: MGatner

README.md

@@ -23,12 +23,14 @@ Provides out-of-the-box user alerts for CodeIgniter 4
 
 Install easily via Composer to take advantage of CodeIgniter 4's autoloading capabilities
 and always be up-to-date:
-* `> composer require tatter/alerts`
+```bash
+composer require tatter/alerts
+```
 
 Or, install manually by downloading the source files and adding the directory to
 `app/Config/Autoload.php`.
 
-Note: The default display template expects [Bootstrap4](https://getbootstrap.com) but is
+> Note: The default display template expects [Bootstrap](https://getbootstrap.com) but is
 easily changed.
 
 ## Configuration (optional)
@@ -37,18 +39,18 @@ The library's default behavior can be changed using its config file. Copy
 **examples/Alerts.php** to **app/Config/Alerts.php** and follow the instructions in the
 comments. If no config file is found the library will use its defaults.
 
+### Styling
+
+By default alerts will be displayed with classes for Bootstrap (not included).
+However, styles can be set to use other frameworks (or you may use your own) by changing
+the `$template` property in the Config file.
+
 ## Usage
 
 If installed correctly CodeIgniter 4 will detect and autoload the library, service, helper,
 and config. Initialize the helper if you want the convenience wrapper function:
-`helper('tatter\alerts');`
+`helper('alerts');`
 
 Then use the helper function `alert($class, $text)` to set an alert for the user's next
 view. Use class methods `$alerts->css()` and `$alerts->display()` to retrieve the styling
 and HTML for the alerts.
-
-## Styles
-
-By default alerts will be displayed with classes for Bootstrap (not included).
-However, styles can be set to use other toolkits (or you may use your own) by changing
-`$template` in the config file.

UPGRADING.md

@@ -0,0 +1,34 @@
+# Upgrade Guide
+
+## Version 2 to 3
+***
+
+> Note: This is a complete refactor! Please be sure to read the docs carefully before upgrading.
+
+* All handling is now routed through `AlertsFilter` - read the docs on setting up the Filter
+* Related, the service, exceptions, and language files have been removed
+* Alerts no longer use session prefixes but are matched to the Config `$classes` - beware of session collision
+* The view templates no longer include a wrapper; if you would like consistent behavior then put your token in an `<aside>` tag:
+```html
+    <aside id="alerts-wrapper">
+        {alerts}
+    </aside>
+```
+* This library no longer provides CSS for the wrapper or positioning; if you would like consistent behavior then include the old CSS:
+```css
+	<!-- CSS for Alerts -->
+	<style>
+		#alerts-wrapper {
+			position: fixed;
+			top: 10%;
+			right: 10px;
+			left: 10px;
+			z-index: 10;
+		}
+		@media screen and (min-width: 768px) {
+			#alerts-wrapper {
+				left: 60%;
+			}
+		}
+	</style>
+```

examples/Alerts.php

@@ -2,31 +2,46 @@
 
 namespace Config;
 
-/*
- *
+/**
  * This file contains example values to change the default library behavior.
  * Recommended usage:
  *	1. Copy the file to app/Config/Alerts.php
  *	2. Set any override variables
  *	3. Remove any lines to fallback to library defaults
- *
  */
 
-class Alerts extends \Tatter\Alerts\Config\Alerts
-{
-    // prefix for SESSION variables and HTML classes, to prevent collision
-    public $prefix = 'alerts-';
+use Tatter\Alerts\Config\Alerts as AlertsConfig;
 
-    /*
-        Template to use for HTML output
-        There must be a corresponding view file for the path/namespace provided
-        Native support for:
-            basic - a minimalist layout internal to this library
-            bootstrap (default) - [https://getbootstrap.com/docs/4.0/components/alerts/#dismissing]
-            foundation - [https://foundation.zurb.com/sites/docs/callout.html#making-closable]
+class Alerts extends AlertsConfig
+{
+    /**
+     * Template to use for HTML output.
+     *
+     * @var string
      */
-    public $template = 'Tatter\\Alerts\\Views\\bootstrap';
+    public $template = 'Tatter\Alerts\Views\Bootstrap4';
 
-    // Whether to check session flashdata for common alert keys
-    public $getflash = true;
+    /**
+     * Mapping of Session keys to their CSS classes.
+     * Note: Some templates may add prefixes to the class,
+     * like Bootstrap "alert-{$class}".
+     *
+     * @var array<string,string>
+     */
+    public $classes = [
+        'primary'   => 'primary',
+        'message'   => 'primary',
+        'secondary' => 'secondary',
+        'notice'    => 'secondary',
+        'success'   => 'success',
+        'danger'    => 'danger',
+        'error'     => 'danger',
+        'errors'    => 'danger',
+        'critical'  => 'danger',
+        'emergency' => 'danger',
+        'warning'   => 'warning',
+        'alert'     => 'warning',
+        'info'      => 'info',
+        'debug'     => 'info',
+    ];
 }

src/Alerts.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace Tatter\Alerts\Collectors;
+
+use CodeIgniter\Debug\Toolbar\Collectors\BaseCollector;
+use Tatter\Alerts\Filters\AlertsFilter;
+
+class Alerts extends BaseCollector
+{
+    /**
+     * Whether this collector has data that can
+     * be displayed in the Timeline.
+     *
+     * @var bool
+     */
+    protected $hasTimeline = false;
+
+    /**
+     * Whether this collector needs to display
+     * content in a tab or not.
+     *
+     * @var bool
+     */
+    protected $hasTabContent = true;
+
+    /**
+     * Whether this collector has data that
+     * should be shown in the Vars tab.
+     *
+     * @var bool
+     */
+    protected $hasVarData = false;
+
+    /**
+     * The 'title' of this Collector.
+     * Used to name things in the toolbar HTML.
+     *
+     * @var string
+     */
+    protected $title = 'Alerts';
+
+    /**
+     * Store of alerts.
+     *
+     * @var array<string[]>
+     */
+    protected $alerts;
+
+    //--------------------------------------------------------------------
+
+    /**
+     * Preloads alerts so they are only gathered once.
+     */
+    public function __construct()
+    {
+        $this->alerts = AlertsFilter::gather(config('Alerts'));
+    }
+
+    //--------------------------------------------------------------------
+
+    /**
+     * Returns the data of this collector to be formatted in the toolbar
+     */
+    public function display(): string
+    {
+        $html = '';
+
+        foreach ($this->alerts as $alert) {
+            [$class, $content] = $alert;
+
+            $html .= '<p><strong>' . ucfirst($class) . '</strong>: ' . esc($content) . '</p>' . PHP_EOL;
+        }
+
+        return $html;
+    }
+
+    //--------------------------------------------------------------------
+
+    /**
+     * Gets the "badge" value for the button.
+     */
+    public function getBadgeValue(): int
+    {
+        return count($this->alerts);
+    }
+
+    //--------------------------------------------------------------------
+
+    /**
+     * Display the icon.
+     *
+     * Icon from https://icons8.com - 1em package
+     * https://icons8.com/icon/pack/data/p1em
+     */
+    public function icon(): string
+    {
+        return 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAAjklEQVQ4ja2TwQmAMAxF3ySKDqLbeCjqxKKOoBPowQSlJNKK/xJK819C0oKvAOwSs9UBK9ACEzB+MVdyLnIgsVmVBLHMRyrEq3xEZxMSgBkoDXAMQPJmHtvZgcZqywEg+dtvHcA9g9qpqNIZDNZl6hZM8xOy4L+DV7MHyTKreq5BNRL7HLMqcK3q029M1gn4Ri2RhwmVWQAAAABJRU5ErkJggg==';
+    }
+}