Merge pull request #1 from AXN-Informatique/develop

Prepare 3.0.0

changelog.md

@@ -1,10 +1,35 @@
 Changelog
 =========
 
+3.0.0 (2021-02-15)
+------------------
+
+- **BBC** Notifier instance is now a singleton
+- **BBC** Add a configuration file and set pnotify5 as default view
+- **BBC** arguments order of `show*()` methods have change (view name at last and optionnal)
+- Add new predefined views:
+  - bootstrap4
+  - bootstrap4-advanced
+  - pnotify5
+- Deprecate old predefined views:
+  - bootstrap3
+  - bootstrap3-advanced
+  - notify
+  - pnotify4
+- Add anothers conveniants helpers:
+  - `notify()`
+  - `notifier()` is now an alias of `notify()`
+  - `notify_info()` shorckut for `notify()->info()`
+  - `notify_success()` shorckut for `notify()->success()`
+  - `notify_warning()` shorckut for `notify()->warning()`
+  - `notify_error()` shorckut for `notify()->error()`
+- Complements and details documentation
+
+
 2.9.0 (2021-02-12)
 ------------------
 
-- Add helper notifier()
+- Add helper `notifier()`
 - Minors enhancements
 
 
@@ -59,25 +84,25 @@ Changelog
 2.1.2 (2017-10-02)
 ------------------
 
-- anothers typos
+- Anothers typos
 
 
 2.1.1 (2017-10-02)
 ------------------
 
-- typo
+- Typo
 
 
 2.1.0 (2017-10-01)
 ------------------
 
-- add support for Laravel 5.5
+- Add support for Laravel 5.5
 
 
 2.0.0 (2017-02-05)
 ------------------
 
-- Laravel 5.4 support
+- Add support for Laravel 5.4
 
 
 1.0.5 (2016-11-02)
@@ -96,22 +121,22 @@ Changelog
 1.0.3 (2016-01-12)
 ------------------
 
-- Complétion composer.json
+- Completion composer.json
 
 
 1.0.2 (2015-11-04)
 ------------------
 
-- Correction échappement des paramètres PNotify dans le template.
+- Correction of escaping PNotify parameters in the template
 
 
 1.0.1 (2015-10-29)
 ------------------
 
-- Ajout jQuery document ready au template PNotify
+- Added "jQuery document ready" to the PNotify template
 
 
 1.0.0 (2015-10-29)
 ------------------
 
-- Première version fonctionnelle
+- First functional version

config/notifier.php

@@ -0,0 +1,26 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default vue
+    |--------------------------------------------------------------------------
+    |
+    | The name of the blade view to use by default :
+    |
+    | - 'notifier::bootstrap3' bootstrap3 (requiert Bootstrap 3) deprecated
+    | - 'notifier::bootstrap3-advanced' bootstrap3-advanced (requiert Bootstrap 3) deprecated
+    | - 'notifier::bootstrap4' bootstrap4 (requiert Bootstrap 4)
+    | - 'notifier::bootstrap4-advanced' bootstrap4-advanced (requiert Bootstrap 4)
+    | - 'notifier::pnotify' pnotify (requiert PNotify 3) deprecated
+    | - 'notifier::pnotify4' pnotify4 (requiert PNotify 4) deprecated
+    | - 'notifier::pnotify5' pnotify5 (requiert PNotify 5)
+    | - 'notifier::sweetalert2' sweetalert2 (requiert SweetAlert 2) incomming
+    | - 'custom-vue' your cutom one
+    |
+    */
+
+    'default_view' => 'notifier::pnotify5',
+
+];

readme.md

@@ -1,6 +1,8 @@
 # Laravel Notifier
 
-Ce package vise à simplifier l'utilisation des notifications dans les interfaces web d'une application Laravel.
+Ce package vise à simplifier l'enregistrement et l'affichage des notifications/alertes dans les interfaces web d'une application Laravel.
+
+**Attention** à ne pas confondre dans Laravel les "[Notifications](https://laravel.com/docs/8.x/notifications)" et les "[Session Flash Data](https://laravel.com/docs/8.x/session#flash-data)" ; ce package utilisent ces dernières et n'a absolument rien à voir aux premières.
 
 
 ## Installation
@@ -43,26 +45,39 @@ to the array of aliases in `config/app.php`:
 
 ### Notifications flash
 
-Pour ajouter des notifications flash, utilisez les fonctions suivantes :
+Les notifications flash sont enregistrées en session et disponibles **pour la requêtte HTTP suivante**.
+
+Typiquement elles permettent d'afficher des confirmations après soumission d'un formulaire.
+
+Cela correspond aux "Flash Data" de Laravel, mais en *typant* les messages afin de piloter plus facilement le rendu à l'écran.
 
-- `info('message')`
-- `success('message')`
-- `warning('message')`
-- `error('message')`
+Pour ajouter des notifications flash, utilisez au choix :
 
-Soit via le helper `notifier()` :
+- Soit via le helper `notify()` (ou son alisa `notifier()`) :
 
 ```php
-notifier()->info('message');
+notify()->info('message');
 
-notifier()->success('message');
+notify()->success('message');
 
-notifier()->warning('message');
+notify()->warning('message');
 
-notifier()->error('message');
+notify()->error('message');
 ```
 
-Soit via la façade :
+- Soit les fonctions helpers raccourcies suivantes :
+
+```php
+notify_info('message');
+
+notify_success('message');
+
+notify_warning('message');
+
+notify_error('message');
+```
+
+- Soit via la façade (façon "historique" de ce package avant la version 2.9) :
 
 ```php
 use Axn\LaravelNotifier\Facade as Notifier;
@@ -78,86 +93,140 @@ Notifier::warning('message');
 Notifier::error('message');
 ```
 
-Et pour afficher ces notifications flash dans vos views Blade, utilisez la fonction `showFlash()` :
+Toutes ces méthodes acceptent un second argument `$title` par exemple :
+
+```php
+notify()->info('message', 'titre');
+```
+
+
+#### Affichage
+
+Et pour afficher ces notifications flash dans vos views Blade, utilisez la méthode `showFlash()` :
 
 ```blade
-notifier()->showFlash('notifier::bootstrap3');
+notify()->showFlash();
 ```
 
-ou
+ou via la façade :
 
 ```blade
-Notifier::showFlash('notifier::bootstrap3');
+Notifier::showFlash();
+```
+
+Cet appel doit être placé selon le template de vue utilisé (voir plus bas).
+
+Par exemple avec un template Bootstrap vous allez le placer là où vous voulez l'afficher ; par contre avec un template PNotify vous allez le placer dans les scripts.
+
+Par défaut le template de vue utilisé est celui du fichier de configuration mais vous pouvez choisir la vue à utiliser pour effectuer le rendu de la notification :
+
+```blade
+notify()->showFlash('notifier::bootstrap3');
 ```
 
-L'argument de cette fonction est le template de vue à utiliser pour effectuer le rendu de la notification.
+ou via la façade :
 
+```blade
+Notifier::showFlash('notifier::bootstrap3');
+```
 
 ### Notifications instantanées
 
-Si vous souhaitez afficher directement des notifications, utilisez les fonctions suivantes :
+Si vous souhaitez afficher directement des notifications non flash, donc **dans la requête HTTP courante**.
+
+Typiquement elles permettent d'afficher les erreurs après soumission d'un formulaire via la variable `$errors` de Laravel.
 
-- `showInfo('view', 'message')`
-- `showSuccess('view', 'message')`
-- `showWarning('view', 'message')`
-- `showError('view', 'message')`
+Pour cela vous pouvez utiliser les fonctions `show*` :
 
-Soit via le helper `notifier()` :
+Soit via le helper `notify()` (ou son alisa `notifier()`) :
 
 ```php
-notifier()->showInfo('notifier::bootstrap3', 'message');
+notify()->showInfo('message');
 
-notifier()->showSuccess('notifier::bootstrap3', 'message');
+notify()->showSuccess('message');
 
-notifier()->showWarning('notifier::bootstrap3', 'message');
+notify()->showWarning('message');
 
-notifier()->showError('notifier::bootstrap3', 'message');
+notify()->showError('message');
 ```
 
 Soit via la façade :
 
 ```php
-Notifier::showInfo('notifier::bootstrap3', 'message');
+Notifier::showInfo('message');
 
-Notifier::showSuccess('notifier::bootstrap3', 'message');
+Notifier::showSuccess('message');
 
-Notifier::showWarning('notifier::bootstrap3', 'message');
+Notifier::showWarning('message');
 
-Notifier::showError('notifier::bootstrap3', 'message');
+Notifier::showError('message');
 ```
 
 Toutes les méthodes `show*` prennent en premier paramètre le template de vue à utiliser
 pour effectuer le rendu de la notification.
 
 
-## Templates de vues disponibles
+## Configuration
+
+Ce package fournit un fichier de configuration.
+
+*Consultez ce fichier pour voir ce que vous pouvez modifier, chacunes des options est documentée.*
+
+Les valeurs de ce fichier sont accessibles de cette façon : `config('notifier.option')` où `option` est la clé du tableau de configuration.
+
+Afin de personnaliser la configuration, vous devez publier le fichier dans votre application en exécutant la commande suivante :
+
+```sh
+php artisan vendor:publish --provider="Axn\LaravelNotifier\ServiceProvider" --tag="config"
+```
+
+Le fichier sera alors copié dans `config/notifier.php` et automatiquement chargé par l'application.
+
+**Astuce :** *ne mettez dans ce fichiers que ce que vous modifiez, le reste sera fusionné depuis le package.*
+
+
+## Templates de vues
 
 Il y a actuellement les templates de vue fournis par le package :
 
-- bootstrap3 *(requiert le framework CSS Bootstrap 3)*
-- bootstrap3-advanced *(requiert le framework CSS Bootstrap 3)*
-- pnotify *(requiert le plugin JS PNotify 3)*
-- pnotify4 *(requiert le plugin JS PNotify 4)*
+- ~~bootstrap3 *(requiert Bootstrap 3)*~~ **deprecated**
+- ~~bootstrap3-advanced *(requiert Bootstrap 3)*~~ **deprecated**
+- bootstrap4 *(requiert Bootstrap 4)*
+- bootstrap4-advanced *(requiert Bootstrap 4)*
+- ~~pnotify *(requiert PNotify 3)*~~ **deprecated**
+- ~~pnotify4 *(requiert PNotify 4)*~~ **deprecated**
+- pnotify5 *(requiert PNotify 5)*
+- sweetalert2 *(requiert SweetAlert 2)* **incomming**
 
 Selon le template utilisé des installations de dépendances peuvent êtres nécessaires.
 
-Par exemple pour les vues "Bootstrap3" il est nécessaire que vous ayez dans votre projet ce dernier.
+Par exemple pour les vues "Bootstrap4" il est nécessaire que vous ayez ce dernier dans votre projet.
 
-Pareil pour les vues qui utilisent pnotify ; celui-ci doit être configuré dans votre projet selon sa version.
+Pareil pour les vues qui utilisent PNotify ; celui-ci doit être configuré dans votre projet selon sa version.
 
 
-### Personnalisation des templates
+### Personnalisation des templates disponibles
 
 Copier les fichiers de vues du package vers le dossier de vues de l'application via la commande :
 
 ```sh
-php artisan vendor:publish
+php artisan vendor:publish --provider="Axn\LaravelNotifier\ServiceProvider" --tag="views"
 ```
 
 Et y effectuer les modification souhaitées.
 
-Vous pouvez aussi créer vos propres templates. Exemple :
+**Astuce :**
+*Ne remplacez les fichiers de vues que ceux que vous personnalisez, les autres seront chargés depuis le package.*
+
+
+### Création de templates personnalisés
+
+Vous pouvez aussi créer vos propres templates.
+
+Pour l'utiliser précisez son utilisation lors de l'affichage, par exemple :
 
 ```php
 Notifier::showFlash('nom-de-la-vue');
 ```
+
+Ou la définissez la dans le fichier de configuration du package.

resources/views/bootstrap4-advanced.blade.php

@@ -0,0 +1,30 @@
+
+<div class="alert alert-{!! ($type === 'error' ? 'danger' : $type) !!} alert-dismissible fade show" role="alert">
+    <div class="d-flex align-items-center">
+        @if ($type === 'success')
+            <span class="fa-stack">
+                <i class="fal fa-circle fa-stack-2x"></i>
+                <i class="fal fa-check fa-stack-1x"></i>
+            </span>
+        @elseif ($type === 'info')
+            <span class="fa-stack">
+                <i class="fal fa-circle fa-stack-2x"></i>
+                <i class="fal fa-info fa-stack-1x"></i>
+            </span>
+        @elseif ($type === 'warning')
+            <i class="fal fa-exclamation-triangle fa-2x"></i>
+        @elseif ($type === 'error')
+            <i class="fal fa-ban fa-2x"></i>
+        @endif
+
+        @if (!empty($title))
+            <strong>{{ $title }}</strong><br>
+        @endif
+
+        {!! $message !!}
+    </div>
+
+    <button type="button" class="close" data-dismiss="alert" aria-label="{!! trans('comon::action.close') !!}">
+      <span aria-hidden="true">&times;</span>
+    </button>
+</div>

resources/views/bootstrap4.blade.php

@@ -0,0 +1,8 @@
+
+<div class="alert alert-{!! ($type === 'error' ? 'danger' : $type) !!}" role="alert">
+    @if (!empty($title))
+        <strong>{{ $title }}</strong><br>
+    @endif
+
+    {{ $message }}
+</div>