Mail Module
The mail
module allows an application to format and send a mail
to users. This module does not define any web interface. It provides
a set of services and methods to send a mail when an event is
received. All this is done through configuration. The module
defines a set of specific ASF components to format and prepare the
email.
Integration
To be able to use the mail
module, you will need to add the following
line in your GNAT project file:
with "awa_mail";
The Mail_Module
type represents the mail module. An instance
of the mail module must be declared and registered when the application
is created and initialized. The module instance can be defined
as follows:
type Application is new AWA.Applications.Application with record
Mail_Module : aliased AWA.Mail.Modules.Mail_Module;
end record;
And registered in the Initialize_Modules
procedure by using:
Register (App => App.Self.all'Access,
Name => AWA.Mail.Modules.NAME,
Module => App.Mail_Module'Access);
Configuration
The mail
module needs some properties to configure the SMTP
server.
Configuration | Default | Description |
---|---|---|
mail.smtp.host | localhost | Defines the SMTP server host name |
mail.smtp.port | 25 | Defines the SMTP connection port |
mail.smtp.enable | 1 | Defines whether sending email is enabled or not |
Sending an email
Sending an email when an event is posted can be done by using
an XML configuration. Basically, the mail
module uses the event
framework provided by AWA. The XML definition looks like:
<on-event name="user-register">
<action>#{userMail.send}</action>
<property name="template">/mail/register-user-message.xhtml</property>
</on-event>
With this definition, the mail template /mail/register-user-message.xhtml
is formatted by using the event and application context when the
user-register
event is posted.
Components
The AWA.Mail.Components
package defines several UI components that represent
a mail message in an ASF view. The components allow the creation, formatting
and sending of a mail message using the same mechanism as the application
presentation layer. Example:
<f:view xmlns="mail:http://code.google.com/p/ada-awa/mail">
<mail:message>
<mail:subject>Welcome</mail:subject>
<mail:to name="Iorek Byrnison">Iorek.Byrnison@svalbard.com</mail:to>
<mail:body>
...
</mail:body>
<mail:attachment value="/images/mail-image.jpg"
fileName="image.jpg"
contentType="image/jpg"/>
</mail:message>
</f:view>
When the view which contains these components is rendered, a mail message
is built and initialized by rendering the inner components. The body and
other components can use other application UI components to render useful
content. The email is send after the mail:message
has finished to render
its inner children.
The mail:subject
component describes the mail subject.
The mail:to
component define the mail recipient.
There can be several recepients.
The mail:body
component contains the mail body.
The mail:attachment
component allows to include some attachment.
Mail Recipients
The AWA.Mail.Components.Recipients package defines the UI components to represent the To, From, Cc and Bcc recipients.
The mail message is retrieved by looking at the parent UI component until a
UIMailMessage
component is found. The mail message recipients are initialized
during the render response JSF phase, that is when Encode_End are called.
Mail Messages
The AWA.Mail.Components.Messages
package defines the UI components
to represent the email message with its recipients, subject and body.
The mail message is retrieved by looking at the parent UI component until a
UIMailMessage
component is found. The mail message recipients are initialized
during the render response JSF phase, that is when Encode_End
are called.
The <mail:body>
component holds the message body. This component can
include a facelet labeled alternative
in which case it will be used
to build the text/plain
mail message. The default content type for
<mail:body>
is text/html
but this can be changed by using the
type
attribute.
<mail:body type='text/html'>
<facet name='alternative'>
The text/plain mail message.
</facet>
The text/html mail message.
</mail:body>
Mail Attachments
The AWA.Mail.Components.Attachments
package defines the UI components
to represent a mail attachment. The mail attachment can be an external
file or may be provided by an Ada bean object.
Ada Beans
Name | Description |
---|---|
userMail | Bean used to send an email with a specific template to the user. |