Skip to content

Commit

Permalink
Merge pull request #26 from froschdesign/hotfix/docs/rework
Browse files Browse the repository at this point in the history 
Updates documentation to add introduction, basic usage and examples for configuration, Bootstrap, application-wide layout
  • Loading branch information
@Ocramius
Ocramius authored Aug 2, 2022
2 parents 86bb1c6 + e1f60f2 commit 7293ba4
Show file tree
Hide file tree
Showing 8 changed files with 239 additions and 89 deletions.
43 changes: 43 additions & 0 deletions docs/book/basic-usage.md
View file
Original file line number Diff line number Diff line change
@@ -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
<?= $this->flashMessenger()->render() ?>
```

Output:

```html
<ul class="success"><li>Album created successfully.</li></ul>
```
11 changes: 7 additions & 4 deletions docs/book/controller-plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```
85 changes: 85 additions & 0 deletions docs/book/cookbook/application-wide-layout.md
View file
Original file line number Diff line number Diff line change
@@ -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' => '<p%s>',
'message_close_string' => '</p>',
'message_separator_string' => '<br>',
],
],
];
```

## 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' => '<p%s>',
'message_close_string' => '</p>',
'message_separator_string' => '<br>',
'classes' => 'custom-default example-class',
],
'success' => [
'message_open_format' => '<p%s>',
'message_close_string' => '</p>',
'message_separator_string' => '<br>',
'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',
],
],
],
];
```
46 changes: 46 additions & 0 deletions docs/book/cookbook/bootstrap.md
View file
Original file line number Diff line number Diff line change
@@ -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' => '<div%s role="alert">',
'message_close_string' => '</div>',
'message_separator_string' => '</div><div%s role="alert">',
'classes' => 'alert alert-primary',
],
'success' => [
'message_open_format' => '<div%s role="alert">',
'message_close_string' => '</div>',
'message_separator_string' => '</div><div%s role="alert">',
'classes' => 'alert alert-success',
],
'warning' => [
'message_open_format' => '<div%s role="alert">',
'message_close_string' => '</div>',
'message_separator_string' => '</div><div%s role="alert">',
'classes' => 'alert alert-success',
],
'error' => [
'message_open_format' => '<div%s role="alert">',
'message_close_string' => '</div>',
'message_separator_string' => '</div><div%s role="alert">',
'classes' => 'alert alert-danger',
],
'info' => [
'message_open_format' => '<div%s role="alert">',
'message_close_string' => '</div>',
'message_separator_string' => '</div><div%s role="alert">',
'classes' => 'alert alert-info',
],
],
],
];
```

This will set the format [for all uses of the view helper](application-wide-layout.md).
5 changes: 5 additions & 0 deletions docs/book/installation.md
View file
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions docs/book/introduction.md
View file
Original file line number Diff line number Diff line change
@@ -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.
104 changes: 20 additions & 84 deletions docs/book/view-helper.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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 = '</li></ul>';
protected $messageOpenFormat = '<ul%s><li>';
protected $messageSeparatorString = '</li><li>';
Expand Down Expand Up @@ -88,83 +86,21 @@ The above code sample then would then generate the following output:
</div>
```

## 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('<div%s>
<button type="button" class="close" data-dismiss="alert" aria-hidden="true">
&times;
</button>
<ul><li>')
->setMessageSeparatorString('</li><li>')
->setMessageCloseString('</li></ul></div>');

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
<div class="alert alert-dismissable alert-success">
<button type="button" class="close" data-dismiss="alert" aria-hidden="true">×</button>
<ul>
<li>Some FlashMessenger Content</li>
<li>You, who's reading the docs, are AWESOME!</li>
</ul>
</div>
```

## 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' => '<div%s><button type="button" class="close"
data-dismiss="alert" aria-hidden="true">&times;</button><ul><li>',
'message_close_string' => '</li></ul></div>',
'message_separator_string' => '</li><li>',
],
],
```

## 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.
<!-- markdownlint-disable MD001 -->
> 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.
<!-- markdownlint-restore -->
9 changes: 8 additions & 1 deletion mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'

0 comments on commit 7293ba4

Please sign in to comment.