Quick links: Content - sections - sub sections
EN FR

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.