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 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.