NAME

Krang::Message - module to handle UI messages in Krang


SYNOPSIS

  use Krang::ClassLoader Message => qw(add_messsage get_messages clear_messages);
  # show the 'invalid_type' message, which requires no parameters
  add_message('invalid_type');
  # show the 'duplicate_url' message, supplying the story_id and url
  add_message('duplicate_url', story_id => $story_id, url => $url);
  # show the 'invalid_title' message defined for Krang::CGI::Story
  # regardless of the current module
  add_message('invalid_title', from_module => 'Krang::CGI::Story');
  # get computed message output
  @messages = get_messages();
  # get messages in a hash by key
  %messages = get_messages(keys => 1);
  # get the text of a message as defined in the the F<lang/messages.LANGUAGE> file.
  $text = get_message_text('invalid_title', 'Krang::CGI::Story');
  # clear messages
  clear_messages();


DESCRIPTION

Krang::Message offers the add_message() and add_alert() functions. These allows you to register a message or alert which will be shown to the user at the next convenient point. In the web UI that will be on the next screen shown.

Messages are specified symbolically, allowing Krang to maintain centralized language-specific databases of message text in lang/messages.LANGUAGE, with LANGUAGE being a RFC3066-style language tag. This allows non-programmers to edit this text. Variable replacement in error text is specified using a Perlish syntax. For example, if the duplicate_url message were specified like this:

  duplicate_url "Duplicate!  The story with ID $id already has the URL $url."

Then the call to add_message() should look like:

  add_message('duplicate_url', id => $id, url => $url);

Messages in lang/messages.LANGUAGE may be specified in per-module blocks. For example, Krang::CGI::Story's messages could be specified like:

  <Module "Krang::CGI::Story">
     invalid_type  "Invalid type!"
     invalid_title "Invalid title!"
  </Module>

This allows different modules to define the same name differently.

Addons can include their own lang/messages.LANGUAGE file which will be read in after the standard Krang file, overriding any duplicated entries.

Any messages found in lang/messages.LANGUAGE can be used by either add_message() or add_alert(). The method chosen will effect how the message is displayed to the user.


INTERFACE