Section: jMessage: short messages between actions
| « jSession: managing sessions | ^ Class utilities | jFile: file processing » |
− Table of content
Often, you'll find useful to display some results/consequences/hints of an action in a subsequent action. As an example, when you redirect a user to your home page after a login failure, it would be interesting to display him a message that the login has failed and the reasons why.
In such cases, jMessage is your best help. In short, jMessage stores
messages in session and expose methods to add, get and clear them.
Session variable ¶
jMessage session variable has a default name : JELIX_MESSAGE.
You can change it through jMessage::session_name static member.
Example :
jMessage::session_name = 'MYAPP_MESSAGE';
Adding a message ¶
Use jMessage::add static method to store a message for further display.
Give your message as first argument. it also accepts an optional type.
Example :
// if login has failed
jMessage::add( 'login failed : incorrect password'); // adds a message of 'default' type
// redirect to home
Display a message ¶
Use the jmessage template plugin to display pending messages.
Example:
// in your home tpl
// display pending messages of 'default' type within an <ul> tag
{jmessage}
Code above will result in the html fragment below:
<ul class="jelix-msg">
<li class="jelix-msg-item-default">login failed : incorrect password</li>
</ul>
Note that Jelix provides default styles for type of messages error, warning,
notice and ok in the module master_admin.
Alternatively you can use the jMessage::get() static method to retrieve a
message in a controller.
Example:
// in your 'home' action
$message = jMessage::get(); // retrieves messages of type 'default'
// assign to your template
$tpl->assign('message', $message);
Note: if your message had not been stored with the default type, you should have
called jMessage::get('mytype') to retrieve it.
You can also retrieve every messages with jMessage::getAll().
Clearing messages ¶
To clear pending messages and thus ensures that your sessions does not get
filled piles of messages, call jMessage::clearAll().
To clear a specific type of messages, use jMessage::clear(). It accepts
an optional type argument. If empty, it clears messages of default type.
