eXtropia: the open web technology company
Technology | Support | Tutorials | Development | About Us | Users | Contact Us
Free support
 ::   Support forums
 ::   Frequently asked questions
 ::   Functional Specifications
 ::   eXtropia Tutorials
 ::   Books by eXtropia
 ::   Other books
 ::   Offsite resources
eXtropia ADT Documentation

Configuration By Example

Prev | Contents | Next

Table of Contents:

[ TOC ]
[ TOC ]

Overview

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
MacintoshMail::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:

  
    my @MAIL_CONFIG_PARAMS = (
        -TYPE              => 'Sendmail',  
        -MAIL_PROGRAM_PATH => '/usr/bin/sendmail'
    );

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

  
    my @MAIL_CONFIG_PARAMS = (
        -TYPE         => 'MailSender',
        -SMTP_ADDRESS => '10.0.0.10'
    );

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:

  
    my @XXX_EVENT_MAIL_SEND_PARAMS = (
        -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.

  
    my @ADMIN_RECEIPT_SEND_PARAMS = (
        -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:

  • AddEventEmailView.ttml

    Defines the contents of the body sent in the email to the administrator if the application is configured to send an email when a new record has been added.

  • ModifyEventEmailView.ttml

    Defines the contents of the body sent in the email to the administrator if the application is configured to send an email when a record is modified.

  • DeleteEventEmailView.ttml

    Defines the contents of the body sent in the email to the administrator if the application is configured to send an email when a record is deleted.

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:

  
    my @ACTION_HANDLER_ACTION_PARAMS = (
        [...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.

    NOTE: Before you get too far into this, you should take some time to read the section on modifying the look-and-feel earlier in this guide as there are lots of configuration gems in that section that you really should know about if you are to extract the most out of this section.

    In this example, we will take the application, remove it from its default HTML frameset so that the application uses only one frame, and wrap the form in a hypothetical site look-and-feel.

    The following figure illustrates the way the application looks before the change.

    To do so, we must do the following:

    1. Modify the display() method of PageTopView.ttml.

    2. Modify the display() method in PageBottomView.ttml

    3. Modify the view parameters.

    4. Modify the default view name.

    5. Optionally modify the @VALID_VIEWS array.

    Once you have completed these steps, the display of the application should change to the following look:

    [ TOC ]

    Step 1: Modify PageTopView.ttml

    This template is used to define the opening HTML for the page. In order to wrap our new site template around the application, we edit the contents of this template:

    The following is the modified PageTopView.ttml:

      
        <HTML>
      <HEAD>
       <TITLE>[% data.script_display_name %]: [% data.page_title %]</TITLE>
      </HEAD>
    [% IF data.css_view_url %]
      <LINK REL = "stylesheet" TYPE = "text/css" 
            HREF = "[% data.css_view_url %]">
    [% END %]
       <BODY>
    
      <TABLE BORDER = "0" WIDTH = "100%" HEIGHT = "100%">
      <TR BGCOLOR = "BLACK">
       <TD COLSPAN = "2" ALIGN = "CENTER">
       <FONT COLOR = "WHITE">
      <H2>The Ugly (but different) Site Template</H2>
      </FONT>
      </TD>
      </TR>
    
        <TR>
        <TD WIDTH = "110" VALIGN = "TOP" BGCOLOR = "000000">
        <FONT COLOR = "WHITE">
        Site Menu
        <BR><A HREF = "blah.html">Home</A>
        <BR><A HREF = "shmoogy.html">Contact Us</A>
        <BR><A HREF = "bloogy.html">Products</A>
        </FONT>
        </TD>
              
        <TD>

    [ TOC ]

    Step 2: Modify PageBottomView.ttml

    Now that we have started wrapping a table around the application, we must close the table in PageBottomView.ttml:

      
            </TD>
        </TR>
        </TABLE>
        </BODY>
        </HTML>

    [ TOC ]

    Step 3: Modify the View parameters

    It is also possible that you will want to change some of the global view parameters. In particular, you might want to change -SCRIPT_DISPLAY_NAME so that you can globally modify the contents of the <TITLE></TITLE> section of every view.

    To change the title, all you need to do is modify -SCRIPT_DISPLAY_NAME as shown in the following example. While you are at it, you'll probably want to modify the URL specific parameters too.

      
        my @VIEW_DISPLAY_PARAMS = (  
       [ ... other view parameters ... ]
        -DOCUMENT_ROOT_URL     => 'http://yourdomain.com/',
        -IMAGE_ROOT_URL        => 'http://yourdomain.com/images/',
        -SCRIPT_DISPLAY_NAME   => 'The Ugly (but different) Site',
       [ ... other view parameters ... ]
    );

    What's more, you can feel free to add your own parameters so that all views can access your custom globals. Consider the following example in which we add a -COPYRIGHT_NOTICE global view parameter.

      
        my @VIEW_DISPLAY_PARAMS = (  
        [ ... other view parameters ... ]
        -DOCUMENT_ROOT_URL     => 'http://yourdomain.com/',
        -IMAGE_ROOT_URL        => 'http://yourdomain.com/images/',
        -SCRIPT_DISPLAY_NAME   => 'The Ugly (but different) Site',
        -COPYRIGHT_NOTICE      => 'Copyright is anachronistic!!!!',
        [ ... other view parameters ... ]
    );

    To access the value of -COPYRIGHT_NOTICE in any template, all you have to do is to write:

      
      [% data.copyright_notice %]

    [ TOC ]

    Step 4: Modify the Default View name

    Of course, now you have modified how the application works. That is, whereas the application was initially set within the HTML frameset defined by FrameView.ttml, you are now using only a single window. As a result, you are going to need to modify @VIEW_DISPLAY_PARAMS in the application executable (eg mlm.cgi) because you no longer require the use of frames. Instead, you want the application to use some other template such as BasicDataView.ttml as the default view as shown in the following code example.

      
        my @VIEW_DISPLAY_PARAMS = (
        [ ... other view parameters ... ]
        -HOME_VIEW                     => ‘BasicDataView’
        [ ... other view parameters ... ]
    );

    [ TOC ]

    Step 5: Optionally add new view to the @VALID_VIEWS array

    If you had actually created a new view, you would also have had to add it to the @VALID_VIEWS array in the application executable as shown below. Of course, so far we have not added a new view, we have just modified an existing one.

      
        my @VALID_VIEWS = qw(
        [ ... other views ... ]
        MyNewView
        [ ... other views ... ]
    );

    [ TOC ]

    Configuration Example 3: Add a Field

    Finally, let's review the steps involved in adding a field to the data source. In this case, let's add an age field. To do so, we must do the following:

    1. Modify the $INPUT_WIDGET_DEFINITIONS and @INPUT_WIDGET_DISPLAY_ORDER variables in the application executable.

    2. Add the new field to the data source field array.

    3. Add the new field to the email display fields array.

    4. EXTRA CREDIT! Optionally add any data handler routines that might be necessary.

    [ TOC ]

    Step 1: Modify the input widget variables

    The first thing that you must do is to modify the views that are used to provide interactivity with the client. These would include the Add, Modify and Delete forms in WebDB or the Comment Form in WebResponder.

    Whichever the case, HTML form input fields are all defined in the application executable using the $INPUT_WIDGET_DEFINITIONS and @INPUT_WIDGET_DISPLAY_ORDER variables in the application executable. The details behind this are discussed in the DataSource Configuration Section of the Customization Chapter in this guide.

    To add the new age field to a form with first name and last name for example, you might use something such as the following:

      
        my $INPUT_WIDGET_DEFINITIONS = {
        age => [
            -DISPLAY_NAME => 'Age',
            -TYPE         => 'textfield’,
            -NAME         => 'age',
            -DEFAULT      => '',
            -SIZE         => 30,
            -MAXLENGTH    => 80
        ],
        fname => [
            -DISPLAY_NAME => 'First Name',
            -TYPE         => 'textfield',
            -NAME         => 'fname',
            -DEFAULT      => '',
            -SIZE         => 30,
            -MAXLENGTH    => 80
        ],
        lname => [
            -DISPLAY_NAME => 'Last Name',
            -TYPE         => 'textfield',
            -NAME         => 'lname',
            -DEFAULT      => '',
            -SIZE         => 30,
            -MAXLENGTH    => 80
        ]
    };
    
    my @INPUT_WIDGET_DISPLAY_ORDER = qw(
            fname
            lname
            age
    );

    [ TOC ]

    Step 2: Add the new field to the datasource field array

    Once the forms are modified, you will have to modify the data source configuration so that the age parameter will be expected.

    Note that the input field that we use for the age parameter is: <INPUT TYPE = "TEXT" NAME = "age">.

    Thus, we must add age to the @DATASOURCE_FIELD_NAMES list.

      
        my @DATASOURCE_FIELD_NAMES = qw(
            item_id
            fname
            lname
            age
    );

    Notice that we added the age field last in the list. The placement is important because it corresponds directly with the way data is stored in certain data sources such as DataSource::File.

      WARNING: If you already have existing records with no age field, you will either have to delete them from the data file or add blank fields after the insertion point. Otherwise, the data source will not correctly reflect the underlying data.

    Specifically, if you were using a file-based data source, you would end up with rows like the following:

      
        id|fname|lname|age
    id|fname|lname|age
    id|fname|lname|age

    [ TOC ]

    Step 3: Add the new field to the email display fields array

    If you are emailing notification or receipts, you will also want to add the age value to the @EMAIL_DISPLAY_FIELDS list in the application executable so that the age value will show up in the bodies of email receipts and notifications.

      
        my @EMAIL_DISPLAY_FIELDS = qw(
            fname
            lname
            age
    );

    [ TOC ]

    Step 4: Add any data handler routines that might be necessary

    Finally, if it makes sense for your application requirements, you can modify the data handler manager to handle the new form field. In this case, we specify that age is a required field and that it must contain a number. Note that if you want more details on data handler managers, check out the Application Development Toolkit Guide in the Further References appendix.

      
        my @ADD_FORM_DH_MANAGER_CONFIG_PARAMS = (
        -TYPE         => 'CGI',
        -CGI_OBJECT   => $CGI,
        -DATAHANDLERS => [qw(
            Exists
            HTML
            Number
            )],
        -ESCAPE_HTML_TAGS => [qw(   
            fname  
            lname
            age
            )],  
        -IS_NUMBER => [qw(
            age
            )],
        -IS_FILLED_IN => [qw(
            fname
            lname
            age
            )]
    );
    [ TOC ]

    Prev | Contents | Next

    [ TOC ]

    [ TOC ]
    Master Copy URL: http://www.extropia.com/support/docs/adt/
    Copyright © 2000-2001 Extropia. All rights reserved.
    [ TOC ]
    Written by eXtropia.
    Last Modified at 10/05/2001