improve documentation

Troopers · Jul 15, 2020 · 4b4c560 · 4b4c560
1 parent 87b4708
commit 4b4c560
Show file tree

Hide file tree

Showing 3 changed files with 107 additions and 85 deletions.
diff --git a/Resources/doc/configuration.md b/Resources/doc/configuration.md
@@ -32,121 +32,101 @@ troopers_alertify:
     ...
 ```
 
-Assetic injections
+Assets injections
 ------------------
 
+First, don't forget that the most of the available libraries here need jquery so you'll need to include it first.
 To add libraries in your views, two ways are possible :
 
-#### Use [AsseticInjectorBundle](https://github.com/Troopers/AsseticInjectorBundle)
-
-Add AsseticInjectorBundle in your `composer.json`, and enable it in your `AppKernel.php`.
-
-Then, add injector tag in your javascripts and stylesheets declaration :
-
-```twig
-{% stylesheets injector="alertify-library"
-    '@AppBundle/Resources/public/css/custom.css'
-%}
-    <link rel="stylesheet" href="{{ asset_url }}" type="text/css" />
-{% endstylesheets %}
-
-{% javascripts injector="alertify-library"
-    '@AppBundle/Resources/public/js/custom.js'
-%}
-    <script src="{{ asset_url }}"></script>
-{% endjavascripts %}
-```
-
-Replace `alertify-library` by the library you want to use.
-
-This is the list of available injections :
-- `alertify-toastr`
-- `alertify-noty`
-- `alertify-notie`
-- `alertify-codrops-notification`
-- `alertify-pushjs` - *only for javascripts injection*
-- `foot` : Add confirm.js and alertify.js - *only for javascripts injection*
-
-#### Add the library yourself
+#### Classic way (recommended) (need `composer req symfony/asset`)
 
 This is how embed libraries in your views without AsseticInjectorBundle :
 
 - For **Toastr** :
 ```twig
-{% stylesheets
-    '@TroopersAlertifyBundle/Resources/public/toastr/css/toastr.css'
-%}
-    <link rel="stylesheet" href="{{ asset_url }}" type="text/css" />
-{% endstylesheets %}
-
-{% javascripts
-    '@TroopersAlertifyBundle/Resources/public/toastr/js/toastr.js'
-%}
-    <script src="{{ asset_url }}"></script>
-{% endjavascripts %}
+{% block stylesheets %}
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/toastr/css/toastr.css') }}" type="text/css" />
+{% endblock %}
 
+{% block javascripts %}
+    <script src="{{ asset('/bundles/troopersalertify/toastr/js/toastr.js') }}"></script>
+{% endblock %}
 ```
 
 - For **PushJs** :
 ```twig
-{% javascripts
-    '@TroopersAlertifyBundle/Resources/public/push.js/push.min.js'
-%}
-    <script src="{{ asset_url }}"></script>
-{% endjavascripts %}
-
+{% block javascripts %}
+    <script src="{{ asset('/bundles/troopersalertify/push.js/push.min.js') }}"></script>
+{% endblock %}
 ```
 
 - For **noty** :
 ```twig
-{% stylesheets
-    '@TroopersAlertifyBundle/Resources/public/noty/css/jquery.noty.css'
-%}
-    <link rel="stylesheet" href="{{ asset_url }}" type="text/css" />
-{% endstylesheets %}
-
-{% javascripts
-    '@TroopersAlertifyBundle/Resources/public/noty/js/jquery.noty.js'
-%}
-    <script src="{{ asset_url }}"></script>
-{% endjavascripts %}
+{% block stylesheets %}
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/noty/css/jquery.noty.css') }}" type="text/css" />
+{% endblock %}
 
+{% block javascripts %}
+    <script src="{{ asset('/bundles/troopersalertify/noty/js/jquery.noty.js') }}"></script>
+{% endblock %}
 ```
 
 - For **notie** :
 ```twig
-{% stylesheets
-    '@TroopersAlertifyBundle/Resources/public/notie/notie.css'
-%}
-    <link rel="stylesheet" href="{{ asset_url }}" type="text/css" />
-{% endstylesheets %}
+{% block stylesheets %}
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/notie/notie.css') }}" type="text/css" />
+{% endblock %}
 
-{% javascripts
-    '@TroopersAlertifyBundle/Resources/public/notie/notie.js'
-%}
-    <script src="{{ asset_url }}"></script>
-{% endjavascripts %}
+{% block javascripts %}
+    <script src="{{ asset('/bundles/troopersalertify/notie/notie.js') }}"></script>
+{% endblock %}
 
 ```
 
 - For **Codrops notification**
 ```twig
-{% stylesheets
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/css/ns-default.css",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/css/ns-style-bar.css",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/css/ns-style-attached.css",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/css/ns-style-growl.css",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/css/ns-style-other.css"
+{% block stylesheets %}
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/codrops-notification/css/ns-default.css') }}" type="text/css" />
+    //and according to the choosed theme :
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/codrops-notification/css/ns-style-bar.css') }}" type="text/css" />
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/codrops-notification/css/ns-style-attached.css') }}" type="text/css" />
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/codrops-notification/css/ns-style-growl.css') }}" type="text/css" />
+    <link rel="stylesheet" href="{{ asset('/bundles/troopersalertify/codrops-notification/css/ns-style-other.cs') }}" type="text/css" />
+{% endblock %}
+
+{% block javascripts %}
+    <script src="{{ asset('/bundles/troopersalertify/codrops-notification/js/classie.js') }}"></script>
+    <script src="{{ asset('/bundles/troopersalertify/codrops-notification/js/modernizr.custom.js') }}"></script>
+    <script src="{{ asset('/bundles/troopersalertify/codrops-notification/js/notificationFx.js') }}"></script>
+{% endblock %}
+```
+
+#### Use [AsseticInjectorBundle](https://github.com/Troopers/AsseticInjectorBundle)
+
+Add AsseticInjectorBundle in your `composer.json`, and enable it in your `AppKernel.php`.
+
+Then, add injector tag in your javascripts and stylesheets declaration :
+
+```twig
+{% stylesheets injector="alertify-library"
+    '@AppBundle/Resources/public/css/custom.css'
 %}
     <link rel="stylesheet" href="{{ asset_url }}" type="text/css" />
 {% endstylesheets %}
 
-{% javascripts
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/js/classie.js",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/js/modernizr.custom.js",
-    "@TroopersAlertifyBundle/Resources/public/codrops-notification/js/notificationFx.js"
+{% javascripts injector="alertify-library"
+    '@AppBundle/Resources/public/js/custom.js'
 %}
     <script src="{{ asset_url }}"></script>
 {% endjavascripts %}
 ```
 
+Replace `alertify-library` by the library you want to use.
+
+This is the list of available injections :
+- `alertify-toastr`
+- `alertify-noty`
+- `alertify-notie`
+- `alertify-codrops-notification`
+- `alertify-pushjs` - *only for javascripts injection*
+- `foot` : Add confirm.js and alertify.js - *only for javascripts injection*
diff --git a/Resources/doc/getting_started.md b/Resources/doc/getting_started.md
@@ -2,16 +2,54 @@
 
 ## Adding message
 
-```
+### In your controller
+
+#### Classic way :
+
+```php
     $this->get('session')->getFlashBag()->add('success', 'ok');
     $this->get('session')->getFlashBag()->add('warning', array('body' => 'ok', 'context' => 'front', 'options' => ['option1' => 'custom value']);
 ```
 
+#### Using the autowire and the helper :
+
+```php
+<?php
+
+namespace App\Controller;
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Routing\Annotation\Route;
+use use Troopers\AlertifyBundle\Helper\AlertifyHelper;
+
+class GrumpyGnomeController extends AbstractController
+{
+    /**
+     * @Route("/grumpy/gnome", name="grumpy_gnome")
+     */
+    public function index(AlertifyHelper $alertify)
+    {
+        $alertify->congrat('Congratulation !');
+        $alertify->scold('WTF are you kidding !');
+        $alertify->inform('Did you know ?');
+        $alertify->warn('Come on, be careful kid !');
+
+        return $this->render('grumpy_gnome/index.html.twig');
+    }
+}
+```
+
 ## Rendering alert message
 
-### Automatically on the `kernel.response` event
+### This is automatically done on the `kernel.response` event
+
+The flash messages are handled in the `kernel.response` thanks to the `Troopers/AlertifyBundle/EventListener/AlertifyListener` class.
+
+If it doesn't display messages, you need to check 2 things :
+- do you have a previous session ? If not, you'll have to create one first or force the injection. You have two way to do this, adding the alertify filter (read below) or adding the `'X-Inject-Alertify' => true` header to your response [Advanced](https://github.com/Troopers/TroopersAlertifyBundle/blob/master/Resources/doc/advanced.md)
+- are the assets correctly loaded ? [Configuration](https://github.com/Troopers/TroopersAlertifyBundle/blob/master/Resources/doc/configuration.md)
 
-### In ajax or for another use, you can use either the `alertify` twig filter
+### To force flash display (ajax, no session mode...), you can use either the `alertify` twig filter in your templates :
 
 ```twig
     {{ app.session|alertify|raw }}

diff --git a/Resources/doc/installation.md b/Resources/doc/installation.md
@@ -14,11 +14,15 @@ Add it in your AppKernel.php (pass to next step with Flex 💪):
             new Troopers\AlertifyBundle\TroopersAlertifyBundle(),
 ```
 
-Warning: make sure the twig engine is turned on in framework.yaml
+Warning: make sure the twig engine is installed and turned on in framework.yaml
+If not :
 
-  - If not, add the following to `config/packages/framework.yaml` (or `config/config.yml` for symfony <4 versions):
+- runs `composer req twig`
+- if needed, add the following to `config/packages/framework.yaml` (or `config/config.yml` for symfony <4 versions)
 
+```yaml
 framework:
     # ...
     templating:
         engines: ['twig']
+```