Editing Sending user messages


== Tested in EPrints versions ==
3.3.10 - 2016-05-17

==Why==
When you execute a job asynchronously (e.g. as a timed event) you may wish to inform the user of the job's completion.  You may also wish to warn the user should something not be configured correctly or if the job failed.
This could either be achieved by sending the user an email (Assuming you have an email address) or by sending them a message within EPrints.

There are 2 places I have encountered user messages thus far - within Plugin Screen actions and from a CGI script.  The method for each is similar but not the same.  Both require:
a type of message 
  *message - informational/positive (default coloured green)
  *warning - alert to some non-critical issue (default coloured orange)
  *error - alert to something critical, like a communications error

a message body, as a DOM object.  This could be via $self->{repository}->make_text("Some Text") or a call to a defined phrase within the repository.

==Screen plugin action==
within a screen plugin action, you can send a message to the current user with via the screen processor:

<source lang="perl">
sub action_screen_action
{
  my ( $self ) = @_;
  $self->{processor}->add_message(
            "error",   #message type - one of 'message', 'warning' or 'error'
            $self->{repository}->make_text("No EPrint found with ID: $eprint_id"),   # the body of the message as a DOM object
  );
}
</source>


==CGI Script (and other non-screen functions)==
From a CGI script, you can send a message to a user via the repository object, as such you need to specify the user, which need not be the current user:

<source lang="perl">
  my $repository = new EPrints::Session;
  my $db = $repository->database;
  my $current_user = $repository->current_user();
  $db->save_user_message(
            $current_user->get_value( "userid" ),   #Userid to receive the message
            "message",                              #Message type
            $repo->html_phrase("some_phrase_identifier", (              #the message body, in this instance a phrase identifier
                        "name" => $current_user->render_value( "name" ) # pin name/value pairs as required for the phrase;
                        )
            )
  );
</source>

[[Category:Snippets]]