diff --git a/docs/book/basic-usage.md b/docs/book/basic-usage.md new file mode 100644 index 0000000..d310bcd --- /dev/null +++ b/docs/book/basic-usage.md @@ -0,0 +1,43 @@ +# Basic Usage + +In the following example, a flash message is set in a controller action and the rendering is done after a redirect. + +## Create a Flash Message + +Store a message in the messenger of a controller action, e.g. `module/Album/Controller/AlbumController.php`: + +```php +namespace Album\Controller; + +use Laminas\Mvc\Controller\AbstractActionController; + +class AlbumController extends AbstractActionController +{ + public function editAction() + { + // Do some work… + + // Add success message + $this->flashMessenger()->addSuccessMessage( + 'Album created successfully.' + ); + + // Redirect + return $this->redirect()->toRoute('album'); + } +} +``` + +## Render a Flash Message + +Render all flash messages in a view script, e.g. `module/Album/view/album/album/index.phtml`: + +```php +flashMessenger()->render() ?> +``` + +Output: + +```html + +``` \ No newline at end of file diff --git a/docs/book/controller-plugin.md b/docs/book/controller-plugin.md index c40341e..3ad2814 100644 --- a/docs/book/controller-plugin.md +++ b/docs/book/controller-plugin.md @@ -85,18 +85,21 @@ current namespace within the session container. ```php public function processAction() { - // ... do some work ... + // Do some work… + $this->flashMessenger()->addMessage('You are now logged in.'); + return $this->redirect()->toRoute('user-success'); } public function successAction() { $return = ['success' => true]; - $flashMessenger = $this->flashMessenger(); - if ($flashMessenger->hasMessages()) { - $return['messages'] = $flashMessenger->getMessages(); + + if ($this->flashMessenger()->hasMessages()) { + $return['messages'] = $this->flashMessenger()->getMessages(); } + return $return; } ``` diff --git a/docs/book/cookbook/application-wide-layout.md b/docs/book/cookbook/application-wide-layout.md new file mode 100644 index 0000000..931559a --- /dev/null +++ b/docs/book/cookbook/application-wide-layout.md @@ -0,0 +1,85 @@ +# Set Application-Wide Layout + +The format for the `FlashMessenger` view helper can be configured for an entire application as well as all uses of the helper. + +`Laminas\View\Helper\Service\FlashMessengerFactory` checks the application +configuration and creates the view helper with the given format options. + +## Set the Format for All Namespaces + +Add the following lines to the local or global configuration file, e.g. `config/autoload/global.config.php`: + +```php +return [ + 'view_helper_config' => [ + 'flashmessenger' => [ + 'message_open_format' => '', + 'message_close_string' => '

', + 'message_separator_string' => '
', + ], + ], +]; +``` + +## Set Formats Individually for Namespaces + +INFO: **New Feature** +Available since version 1.8.0 + +Add the following lines to the local or global configuration file, e.g. `config/autoload/global.config.php`: + +```php +return [ + 'view_helper_config' => [ + 'flashmessenger' => [ + 'default' => [ + 'message_open_format' => '', + 'message_close_string' => '

', + 'message_separator_string' => '
', + 'classes' => 'custom-default example-class', + ], + 'success' => [ + 'message_open_format' => '', + 'message_close_string' => '

', + 'message_separator_string' => '
', + 'classes' => 'custom-success example-class', + ], + 'warning' => [ + // … + ], + 'error' => [ + // … + ], + 'info' => [ + // … + ], + ], + ], +]; +``` + +If the default unordered list should be retained, then set only the classes: + +```php +return [ + 'view_helper_config' => [ + 'flashmessenger' => [ + 'default' => [ + 'classes' => 'custom-default', + ], + 'success' => [ + 'classes' => 'custom-success', + ], + 'warning' => [ + 'classes' => 'custom-warning', + ], + 'error' => [ + 'classes' => 'custom-error', + ], + 'info' => [ + 'classes' => 'custom-info', + ], + ], + ], +]; +``` diff --git a/docs/book/cookbook/bootstrap.md b/docs/book/cookbook/bootstrap.md new file mode 100644 index 0000000..78f9439 --- /dev/null +++ b/docs/book/cookbook/bootstrap.md @@ -0,0 +1,46 @@ +# Use Alerts from Bootstrap + +To use the syntax of the [alerts from the Bootstrap CSS framework](https://getbootstrap.com/docs/5.2/components/alerts/) for the output of the view helper, the configuration of the message format must be adjusted. + +To do that, add the following lines to the local or global configuration file, e.g. `config/autoload/global.config.php`: + +```php +return [ + 'view_helper_config' => [ + 'flashmessenger' => [ + 'default' => [ + 'message_open_format' => '', + 'message_close_string' => '', + 'message_separator_string' => '', + 'classes' => 'alert alert-primary', + ], + 'success' => [ + 'message_open_format' => '', + 'message_close_string' => '', + 'message_separator_string' => '', + 'classes' => 'alert alert-success', + ], + 'warning' => [ + 'message_open_format' => '', + 'message_close_string' => '', + 'message_separator_string' => '', + 'classes' => 'alert alert-success', + ], + 'error' => [ + 'message_open_format' => '', + 'message_close_string' => '', + 'message_separator_string' => '', + 'classes' => 'alert alert-danger', + ], + 'info' => [ + 'message_open_format' => '', + 'message_close_string' => '', + 'message_separator_string' => '', + 'classes' => 'alert alert-info', + ], + ], + ], +]; +``` + +This will set the format [for all uses of the view helper](application-wide-layout.md). diff --git a/docs/book/installation.md b/docs/book/installation.md new file mode 100644 index 0000000..be1198c --- /dev/null +++ b/docs/book/installation.md @@ -0,0 +1,5 @@ +# This Is Only a Placeholder + +The content of this page can be found under: + +https://github.com/laminas/documentation-theme/blob/master/theme/pages/installation.html diff --git a/docs/book/introduction.md b/docs/book/introduction.md new file mode 100644 index 0000000..f29b412 --- /dev/null +++ b/docs/book/introduction.md @@ -0,0 +1,25 @@ +# Introduction + +Giving feedback to a user is an important part of a good application. +Flash messages provide notifications to the user, such as for successful form submissions, failure to save data in the database, and incorrect authentication credentials. +A message is created at the end of one request, and shown to the user in the next request. +Flash messages are self-expiring and session-based. + +To create and expose flash messages in a laminas-mvc-based application, this packages provides: + +- [a controller plugin to create and retrieve messages](controller-plugin.md) +- [a view helper to render the messages](view-helper.md) + +A flash message is set in a controller and then rendered in a view script. + +## Namespaces + +The controller plugin and the view helper support different types of messages: + +- `default` +- `info` +- `success` +- `warning` +- `error` + +These namespaces provide support for handling different output formats. diff --git a/docs/book/view-helper.md b/docs/book/view-helper.md index d1cf4c0..0e5be90 100644 --- a/docs/book/view-helper.md +++ b/docs/book/view-helper.md @@ -1,7 +1,6 @@ # FlashMessenger View Helper -The `FlashMessenger` helper is used to render the messages of the -[FlashMessenger controller plugin](controller-plugin.md). +The `FlashMessenger` view helper is used to render the messages of the [FlashMessenger controller plugin](controller-plugin.md). ## Basic Usage @@ -55,10 +54,9 @@ look like this: Aside from modifying the rendered CSS classes of the `FlashMessenger`, you are furthermore able to modify the generated HTML as a whole to create even more distinct visuals for your flash messages. The default output format is defined -within the source code of the `FlashMessenger` view helper itself. +within the source code of the `FlashMessenger` view helper. ```php -// Laminas/View/Helper/FlashMessenger.php#L41-L43 protected $messageCloseString = ''; protected $messageOpenFormat = '
  • '; protected $messageSeparatorString = '
  • '; @@ -88,83 +86,21 @@ The above code sample then would then generate the following output: ``` -## Sample Modification for Twitter Bootstrap 3 - -Taking all the above knowledge into account, we can create a nice, highly usable -and user-friendly rendering strategy using the -[Bootstrap front-end framework](http://getbootstrap.com/) version 3 layouts: - -```php -// In any of your .phtml files: -$flash = $this->flashMessenger(); -$flash->setMessageOpenFormat(' - -
    • ') - ->setMessageSeparatorString('
    • ') - ->setMessageCloseString('
    '); - -echo $flash->render('error', ['alert', 'alert-dismissible', 'alert-danger']); -echo $flash->render('info', ['alert', 'alert-dismissible', 'alert-info']); -echo $flash->render('default', ['alert', 'alert-dismissible', 'alert-warning']); -echo $flash->render('success', ['alert', 'alert-dismissible', 'alert-success']); -``` - -The output of the above example would create dismissable `FlashMessages` with -the following HTML markup. The example only covers one type of `FlashMessenger` -output; if you would have several `FlashMessages` available in each of the -rendered `namespaces`, then you would receive the same output multiple times -only having different CSS classes applied. - -```html -
    - -
      -
    • Some FlashMessenger Content
      • -
    • You, who's reading the docs, are AWESOME!
      • -
    -
    -``` - -## Alternative Configuration of the ViewHelper Layout - -`Laminas\View\Helper\Service\FlashMessengerFactory` checks the application -configuration, making it possible to set up the `FlashMessenger` strings through -your `module.config.php`, too. The next example will set up the output to be -identical with the above Twitter Bootstrap 3 Example - -```php -'view_helper_config' => [ - 'flashmessenger' => [ - 'message_open_format' => '
    • ', - 'message_close_string' => '
    ', - 'message_separator_string' => '
  • ', - ], -], -``` - -## IDE auto-completion in templates - -The `Laminas\Mvc\Plugin\FlashMessenger\View\HelperTrait` trait can be used to -provide auto-completion for modern IDEs. It defines the aliases of the view -helpers in a DocBlock as `@method` tags. - -### Usage - -In order to allow auto-completion in templates, `$this` variable should be -type-hinted via a DocBlock at the top of your template. It is recommended that -you always add the `Laminas\View\Renderer\PhpRenderer` as the first type, so that -the IDE can auto-suggest the default view helpers from `laminas-view`. Next, chain -the `HelperTrait` from `laminas-i18n` with a pipe symbol (a.k.a. vertical bar) `|`: - -```php -/** - * @var Laminas\View\Renderer\PhpRenderer|Laminas\Mvc\Plugin\FlashMessenger\View\HelperTrait $this - */ -``` - -You may chain as many `HelperTrait` traits as you like, depending on view -helpers from which Laminas component you are using and would like to -provide auto-completion for. + +> TIP: **IDE Auto-Completion in Templates** +> The `Laminas\Mvc\Plugin\FlashMessenger\View\HelperTrait` trait can be used to provide auto-completion for modern IDEs. It defines the aliases of the view helpers in a DocBlock as `@method` tags. +> +> ### Usage +> +> In order to allow auto-completion in templates, `$this` variable should be type-hinted via a DocBlock at the top of a template. +> It is recommended that always the `Laminas\View\Renderer\PhpRenderer` is added as the first type, so that the IDE can auto-suggest the default view helpers from `laminas-view`. +> The `HelperTrait` from `laminas-mvc-plugin-flashmessenger` can be chained with a pipe symbol (a.k.a. vertical bar) `|`: +> +> ```php +> /** +> * @var Laminas\View\Renderer\PhpRenderer|Laminas\Mvc\Plugin\FlashMessenger\View\HelperTrait $this +> */ +> ``` +> +> The `HelperTrait` traits can be chained as many as needed, depending on which view helpers from the different Laminas component are used and where the auto-completion is to be made. + diff --git a/mkdocs.yml b/mkdocs.yml index 02d66a2..e1073e8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,18 @@ docs_dir: docs/book site_dir: docs/html nav: - Home: index.md + - Introduction: introduction.md + - Installation: installation.md + - "Basic Usage": basic-usage.md - "Controller Plugin": controller-plugin.md - "View Helper": view-helper.md + - Cookbook: + - "Set Application-Wide Layout": cookbook/application-wide-layout.md + - "Use Alerts from Bootstrap": cookbook/bootstrap.md site_name: laminas-mvc-plugin-flashmessenger site_description: 'Plugin for creating and exposing flash messages via laminas-mvc controllers' repo_url: 'https://github.com/laminas/laminas-mvc-plugin-flashmessenger' extra: project: MVC - show_special_homepage: true + installation: + module_class: 'Laminas\Mvc\Plugin\FlashMessenger\Module'