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

• add_message('name');
  
• add_message('name', param => 'value', ...);
  
• add_message('name', from_module => 'Krang::Module');
  
Adds a message to the current list of messages. The first parameter is always the message identifier, which must appear in lang/messages.LANGUAGE. It must either be in the block for the current module or outside of any block. Any parameters after the message name are parameters to the message, except for _from_module which sets an alternate module name to use to lookup the message definition.

If the module inherits from one or more modules those blocks will be searched if the module's block does not define the requested message name.

• add_alert('name');
  
• add_alert('name', param => 'value', ...);
  
• add_alert('name', from_module => 'Krang::Module');
  
Adds an alert to the current list of messages. The first parameter is always the message identifier, which must appear in lang/messages.LANGUAGE. It must either be in the block for the current module or outside of any block. Any parameters after the alert name are parameters to the alert, except for from_module which sets an alternate module name to use to lookup the message definition.

If the module inherits from one or more modules those blocks will be searched if the module's block does not define the requested alert name.

• @messages = get_messages();
  
• @messages = get_messages(dups => 1);
  
• %messages = get_messages(keys => 1);
  
Returns the computed messages set by calls to add_message(). By default this list contains only unique messages, but call with dups set to 1 to suppress this behavior. When called with keys set to 1 returns a hash of messages keyed by message identifier.
• @alerts = get_alerts();
  
• @alerts = get_alerts(dups => 1);
  
• %alerts = get_alerts(keys => 1);
  
Returns the computed alerts set by calls to add_alert(). By default this list contains only unique alerts, but call with dups set to 1 to suppress this behavior. When called with keys set to 1 returns a hash of alerts keyed by alert identifier.
• get_message_text($key, $class [, %args ]);
  
Returns the message text for the specified $key in the appropriate $class. If ther text has variables for substitution, they can be provided by using passing in extra %args.
• clear_messages();
  
Clears the current list of messages. This should be called after outputing the messages to the user.
• clear_alerts();
  
Clears the current list of alerts. This should be called after outputing the alerts to the user.