Merge pull request #39 from froschdesign/hotfix/docs/basic-usage

Updates and extends the basic usage to correct and add the usage with namespaces

Author: froschdesign

.github/workflows/docs-build.yml

@@ -3,8 +3,7 @@ name: docs-build
 on:
   release:
     types: [published]
-  repository_dispatch:
-    types: docs-build
+  workflow_dispatch:
 
 jobs:
   build-deploy:
@@ -13,5 +12,5 @@ jobs:
       - name: Build Docs
         uses: laminas/documentation-theme/github-actions/docs@master
         env:
-          "DOCS_DEPLOY_KEY": ${{ secrets.DOCS_DEPLOY_KEY }}
-          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/book/basic-usage.md

@@ -1,6 +1,9 @@
 # Basic Usage
 
-In the following example, a flash message is set in a controller action and the rendering is done after a redirect.
+A typical use case is to set a flash message in a controller action and render it in a view script after a redirect.
+The following example shows the use of a success message.
+
+Before starting, make sure laminas-mvc-plugin-flashmessenger is [installed and configured](installation.md).
 
 ## Create a Flash Message
 
@@ -30,14 +33,142 @@ class AlbumController extends AbstractActionController
 
 ## Render a Flash Message
 
-Render all flash messages in a view script, e.g. `module/Album/view/album/album/index.phtml`:
+Render all added success messages in a view script, e.g. `module/Album/view/album/album/index.phtml`:
 
-```php
-<?= $this->flashMessenger()->render() ?>
-```
+<!-- markdownlint-disable MD038 MD009 MD046 -->
+=== "Name Usage"
+    ```php
+    <?= $this->flashMessenger()->render('success') ?>
+    ```
+
+=== "Constant Usage"
+    ```php
+    <?= $this->flashMessenger()->render(
+      Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger::NAMESPACE_SUCCESS
+    ) ?>
+    ```
+<!-- markdownlint-restore -->
 
 Output:
 
 ```html
 <ul class="success"><li>Album created successfully.</li></ul>
-```
+```
+
+## Usage of Namespaces
+
+The flash messenger supports namespaces.
+This allows to render messages of different types in different places.
+
+### Create Flash Messages for Different Namespaces
+
+Store a `success` message in the messenger of a controller action:
+
+```php
+$this->flashMessenger()->addSuccessMessage('…');
+```
+
+Store an `info` message in the messenger of a controller action:
+
+```php
+$this->flashMessenger()->addInfoMessage('…');
+```
+
+Store a `warning` message in the messenger of a controller action:
+
+```php
+$this->flashMessenger()->addWarningMessage('…');
+```
+
+Store an `error` message in the messenger of a controller action:
+
+```php
+$this->flashMessenger()->addErrorMessage('…');
+```
+
+### Render Flash Messages for Different Namespaces
+
+Render all added `success` messages in a view script:
+
+<!-- markdownlint-disable MD038 MD009 MD046 -->
+=== "Name Usage"
+    ```php
+    <?= $this->flashMessenger()->render('success') ?>
+    ```
+
+=== "Constant Usage"
+    ```php
+    <?= $this->flashMessenger()->render(
+      Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger::NAMESPACE_SUCCESS
+    ) ?>
+    ```
+<!-- markdownlint-restore -->
+
+Render all added `info` messages in a view script:
+
+<!-- markdownlint-disable MD038 MD009 MD046 -->
+=== "Name Usage"
+    ```php
+    <?= $this->flashMessenger()->render('info') ?>
+    ```
+
+=== "Constant Usage"
+    ```php
+    <?= $this->flashMessenger()->render(
+      Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger::NAMESPACE_INFO
+    ) ?>
+    ```
+<!-- markdownlint-restore -->
+
+Render all added `warning` messages in a view script:
+
+<!-- markdownlint-disable MD038 MD009 MD046 -->
+=== "Name Usage"
+    ```php
+    <?= $this->flashMessenger()->render('warning') ?>
+    ```
+
+=== "Constant Usage"
+    ```php
+    <?= $this->flashMessenger()->render(
+      Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger::NAMESPACE_WARNING
+    ) ?>
+    ```
+<!-- markdownlint-restore -->
+
+Render all added `error` messages in a view script:
+
+<!-- markdownlint-disable MD038 MD009 MD046 -->
+=== "Name Usage"
+    ```php
+    <?= $this->flashMessenger()->render('error') ?>
+    ```
+
+=== "Constant Usage"
+    ```php
+    <?= $this->flashMessenger()->render(
+      Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger::NAMESPACE_ERROR
+    ) ?>
+    ```
+<!-- markdownlint-restore -->
+
+### Use Default Namespace
+
+The flash messenger supports a default namespace which does not represent an explicit status.
+
+Store a `default` message in the messenger of a controller action:
+
+```php
+$this->flashMessenger()->addMessage('…');
+```
+
+Render all added `default` messages in a view script:
+
+```php
+<?= $this->flashMessenger()->render() ?>
+```
+
+## Learn More
+
+- [The controller plugin](controller-plugin.md)
+- [The view helper](view-helper.md)