Skip to content

Adding docs for flash messages #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: 5.x
Choose a base branch
from
Open

Adding docs for flash messages #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
57986aa
Adding docs for flash messages
andersonjeccel Jun 18, 2025
297d9fc
Fixing wrong path
andersonjeccel Jun 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/design/flash_messages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
Implementing flash messages
###########################

Flash messages are temporary notifications that appear at the top of the page to inform users about the result of an action.

Check warning on line 4 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Users' instead of 'users'.

Raw Output:
{"message": "[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Users' instead of 'users'.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 4, "column": 89}}}, "severity": "INFO"}

Check warning on line 4 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Landing Page' instead of 'page'.

Raw Output:
{"message": "[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Landing Page' instead of 'page'.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 4, "column": 74}}}, "severity": "INFO"}

Backend (PHP) implementation
****************************

Add your translation strings to ``{bundle}/Translations/en_US/flashes.ini``:

**In controllers:**

.. code-block:: php

// Success message
$this->addFlashMessage('mautic.core.notice.created', [
'%name%' => $entity->getName()
]);

// Error message
$this->addFlashMessage('mautic.core.error.generic', [], 'error');

The first parameter is the translation key, the second is an array of parameters for the translation, and the third is the message type (default is ``notice``).

Check warning on line 23 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 23, "column": 1}}}, "severity": "INFO"}

Frontend (JavaScript) implementation
************************************

Add your translation strings to ``{bundle}/Translations/en_US/javascript.ini``:

.. code-block:: ini

mautic.core.notice.my_success_message="Success message here!"
mautic.core.error.my_error_message="Error message here!"

Create the flash message using one of these helper functions:
- Mautic.addFlashMessage(message) - Generic flash message

Check warning on line 36 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 36, "column": 25}}}, "severity": "INFO"}
- Mautic.addInfoFlashMessage(message) - Info/success flash message

Check warning on line 37 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 37, "column": 29}}}, "severity": "INFO"}
- Mautic.addErrorFlashMessage(message) - Error flash message

Check warning on line 38 in docs/design/flash_messages.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/design/flash_messages.rst", "range": {"start": {"line": 38, "column": 30}}}, "severity": "INFO"}

Pass the result to Mautic.setFlashes() to display it.

.. code-block:: javascript

var message = Mautic.translate('mautic.core.notice.my_success_message');
var flashMessage = Mautic.addInfoFlashMessage(message);
Mautic.setFlashes(flashMessage);

var message = Mautic.translate('mautic.core.error.my_error_message');
var flashMessage = Mautic.addErrorFlashMessage(message);
Mautic.setFlashes(flashMessage);
1 change: 1 addition & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ There are several ways to support Mautic other than contributing with code.
design/feedback
design/labelling
design/notifications
design/flash_messages
design/protip
design/quick_filters
design/retrieving_system_information
Expand Down
Loading