Chapter: 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 very interesting to display him a message that is 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 jMessage template plugin to display messages pending.
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:
Or alternatively use 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.
