eXtropia ADT Documentation

Configuration By Example

Table of Contents:

[ TOC ]
[ TOC ]


So far we have focused on getting the default application to run in your local web server environment. We have also presented a general list of configurable elements of the application such as data handlers, data sources, and mailers.

However, there is a good chance that you feel all dressed up with nowhere to go. It has been our experience that it is hard to really give users the intuition necessary to personalize the applications without actually having them get their hands dirty and play around with the code.

So in this section, we'll demonstrate by example how you can begin to leverage the power of the generic application to create your own unique instances. Specifically, we will demonstrate a few modifications that we hope will help give you the intuition necessary to configure the application more dramatically. These modifications include the following:

  1. Change the mailing configuration.

  2. Modify the look-and-feel.

  3. Add a new field

[ TOC ]

Configuration Example 1: Mailing Configuration

Perhaps the first thing that any application administrator will want to do is to enable mailing in the default installation. As we said earlier, we have disabled mailing in all the applications by default because the usage of mail tends to be extremely site-specific.

As a result, if you want to enable mail, you must perform a few modifications.

Specifically, enabling mail involves four steps:

  1. Configure a mail driver.

  2. Personalize the mail send parameters.

  3. Change the email body views.

  4. Turn on the mailing flags.

[ TOC ]

Step 1: Configure a Mail Driver

In order to actually send an email, you must specify a mail driver that works on your system. Fortunately, there are Extropia::Mail drivers for just about any platform one could run a web server on.

Nevertheless, most users will choose one of the drivers in the following table.

PlatformRecommended Driver
UNIXMail::Sendmail or Mail::MailSender
WindowsMail::Blat, Mail::NTSendmail or Mail::MailSender

Configuring a mail driver is simple. All you must do is to modify @MAIL_CONFIG_PARAMS with the driver-specific parameters for whatever Extropia::Mail driver you want to use.

For example, to use Mail::Sendmail, you would use something like:

        -TYPE              => 'Sendmail',  
        -MAIL_PROGRAM_PATH => '/usr/bin/sendmail'

Likewise, to use Mail::MailSender you would use a configuration like the following:

        -TYPE         => 'MailSender',
        -SMTP_ADDRESS => ''

Note that each driver will have its own set of parameters. This will be the case for almost every configuration parameter defined by the application. To find out what these parameters are, consult the eXtropia Application Development Toolkit Guide described in the Further References chapter.

[ TOC ]

Step 2: Change the Send Params

Once the mail driver is configured, you must modify the mail send parameters. Specifically, you will want to specify email addresses specific to your site. By default, the send parameters are configured like so:

        -FROM     => 'you@yourdomain.com',
        -TO       => 'you@yourdomain.com',
        -REPLY_TO => 'you@yourdomain.com',
        -SUBJECT  => 'WebDB Delete'

    [....mail send parameter definitions for any other mail events
    such as additions or deletions....]

Notice that there is one send parameter defined for each type of mail that the application sends. Thus, in an application that supports deleting, in order to configure the mail that is sent to the administrator whenever someone deletes a record, you would edit @DELETE_EVENT_MAIL_SEND_PARAMS.

To modify the parameters, simply change you@yourdomain.com to the actual email address that you wish to use. You might also take the opportunity to modify the subject as well.

Note that the -TO, -CC, and -BCC parameters may accept either a single email address or a reference to an array of multiple email addresses such as in the following example.

        -FROM     => $CGI->param('email'),
        -TO       => [qw(you@yourdomain.com me@mydomain.com)],
        -CC       => 'you@yourdomain.com',
        -BCC      => 'you@yourdomain.com',
        -REPLY_TO => $CGI->param('email'),
        -SUBJECT  => 'Web Responder Entry'

[ TOC ]

Step 3: Change the Email Body Views

The bodies of the emails sent out are actually defined as templates located in the HTMLTemplates directory.

Typically, there will be one email view per email that is generated by the application. The applications can use the default email templates:

Modifying the contents of one of these views is fairly straightforward. Since it's an email template, all you have to change is the plain text. If you want to change the template logic, please refer to the template toolkit manual.

[ TOC ]

Step 4: Turn on the Mailing Flags

Finally, in order to actually enable mailing, you must explicitly turn on the feature by editing @APPLICATION_CONFIG_PARAMS such as demonstrated below:

        [...lots of other application configuration parameters...]
        -SEND_EMAIL_ON_DELETE_FLAG     => 1,
        -SEND_EMAIL_ON_MODIFY_FLAG     => 1,
        -SEND_EMAIL_ON_ADD_FLAG        => 1,
        [...lots of other application configuration parameters...]

Note that for a configuration option such as those shown above a value of ``1'' turns on the feature and a value of ``0'' turns it off.

[ TOC ]

Configuration Example 2: Modifying the Look-and-Feel

One of the first things any new application administrator will want to do is to change the look-and-feel so that the application will blend into an existing site.

Let's do that.