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 WebDB Documentation

Installation Guide


[ TOC ]
[ TOC ]

Overview

If you just want to install the application and start running it, you've come to the right place!

This chapter specifically centers around the steps involved with installing WebDB. However, as mentioned in the previous chapter, we do assume quite a bit of knowledge of both general CGI and how eXtropia applications work. However, we liberally refer back to the general eXtropia Applications Guide described in Appendix A: Further References.

[ TOC ]


The 12 Step Checklist

We start out first with our famous 12-Step checklist to installing any eXtropia application. For further info on the history and details behind the 12-Step list, consult the eXtropia Applications Guide.

As a quick reminder, here are the 12-Steps:

  1. Prepare your environment to run CGI applications.

  2. Obtain the application installation file (webdb.tar).

  3. Unpack the application installation file on your web server.

  4. Set the file and directory permissions correctly.

  5. Fix the reference to the Perl executable on first line of the application executable (webdb.cgi).

  6. Define site-specific parameters by modifying configuration variables in the application executable (webdb.cgi).

  7. Modify the look-and-feel by editing or creating views (webdb/Views/eXtropia).

  8. Run the application using a web browser.

  9. Debug the application if any debugging is required.

  10. Review the security of the application.

    In particular, move administrative and data files out of web documents tree.

  11. Submit the application for user testing.

  12. Register yourself as a user by sending an email to register@extropia.com.

[ TOC ]


Step 1: Prepare your Site

The first step in the process of installing the application is to prepare your environment for CGI execution. If you are not sure how to do this, consult the eXtropia Applications Guide.

[ TOC ]


Step 2: Obtain the Installation File

To obtain the latest version of this application, we recommend that you go straight to http://www.extropia.com/. Mirror-sites and CD-ROMS are not guaranteed to have the truly latest versions of our software at any given time.

[ TOC ]


Steps 3 and 4: Unpacking the Archive File and Setting Permissions

Though the details of unpacking and permissioning are covered in depth in the eXtropia Applications Guide discussed in Appendix A: Further References, we include the following basic guidelines for your convenience:

[ TOC ]


UNIX-based web servers

Use tar xvfz webdb.tar.gz to unpack.

If that does not work,

Use gunzip webdb.tar.gz

THEN

Use tar xvf webdb.tar to unpack.

[ TOC ]


Windows-based web servers or Windows-based workstation

Use a program such as WINZIP to unpack.

[ TOC ]


Mac-based web server

Use a program such as Stuffit Expander.

Once unpacked, the application files will expand into the default directory structure shown in the directory tree further below. The following list provides a set of rules for permissioning:

Directory structure and permissioning:

 
    webdb                                             r-xr-xr-x
        address_book.cgi                              r-xr-xr-x
        inventory_manager.cgi                         r-xr-xr-x
        news.cgi                                      r-xr-xr-x
        project_tracker.cgi                           r-xr-xr-x
        Views                                         r-xr-xr-x
            eXtropia
                AuthManager                           r-xr-xr-x
                    CGIViews.pm                       r--r--r--
                StandardTemplates                     r-xr-xr-x
                    BottomFrameView                   r--r--r--
                    ErrorDisplayView                  r--r--r--
                    FrameView                         r--r--r--
                    TopFrameView                      r--r--r--
                    PageTopView                       r--r--r--
                    PageBottomView                    r--r--r--
            WebDB                                     r-xr-xr-x
                AddressBook                           r-xr-xr-x
                    AddEventEmailView.pm              r--r--r--
                    ModifyEventEmailView.pm           r--r--r--
                    DeleteEventEmailView.pm           r--r--r--
                    DetailsView.pm                    r--r--r--
                    AddRecordView.pm                  r--r-r--
                    BasicDataView.pm                  r--r--r--
                    ModifyRecordView.pm               r--r--r--
                    RecordSetDetailsView.pm           r--r--r--
                    SearchBoxView.pm                  r--r--r--
                InventoryManager (same views as AddressBook)
                News (same views as AddressBook)
                ProjectTracker (same views as AddressBook)
        Apps                                          r-xr-xr-x
            eXtropia                                  r-xr-xr-x
                WebDB.pm                              r--r--r--
        Modules                                       r-xr-xr-x
            There are a heck of a lot of modules. 
            You can see a list of commonly used 
            modules in the eXtropia Application Guide.
        Datafiles                                     rwxrwxrwx
            address_book.dat                          rw-rw-rw-
            address_book_users.dat                    rw-rw-rw-
            address_book.log                          rw-rw-rw-
            [each of the other three apps have these three files]

As you can see above, unlike most other eXtropia applications that have only one application executable, WebDB has four. This is because we wanted to give you a better sense of the possibilities by example. However, don't let the number of application executable unnerve you.

If you read them, you will see that they are practically the same. For the most part, the only differences are in the views, the data source configuration, and the configuration of the view parameters.

[ TOC ]


Step 5: Modify the Perl Path

In order to run the application you must make sure that the first line of the application executable (eg. address_book.cgi) points to your local version of Perl. If you open the application executable in a text editor, you will see that by default, the application expects that Perl is installed in the directory /usr/bin. That is, by default, the first line of the file reads:

 
    #!/usr/bin/perl

If your copy of Perl is located elsewhere, you must modify this one line to reflect the difference. For example, if your copy of Perl is located in the directory /opt/bin, the first line will read:

 
    #!/opt/bin/perl

If you have questions about how to find out where your copy of Perl is located, which version of Perl is required, or if you are using a Windows-based web server, consult the eXtropia Applications Guide discussed in Appendix A: Further References. Also remember that the reference to Perl must absolutely be on the very first line of the file.

[ TOC ]


Step 6: Configure the Application

NOTE: If you are one of the lucky ones, and you are using a web server configuration that matches the one we use at eXtropia, you can probably fire up the application at this point and use it in its default state.

In order to find out, we recommend skipping to Step 8 right now and trying to run the application using a web browser.

Most likely, you will still need to return to this section to make the application work exactly the way you want it to rather than the way it is configured by default. But at this stage it is useful to see if it works out-of-the-box.

When configuring this application, you will be concerned primarily with modifying the configuration parameters defined in the application executable. We have already discussed how the configuration of an eXtropia application executable works in Chapter 3 so we won't repeat that here.

Instead, we will look at each of the configuration parameters in the application executable and explain what they do relative to this specific application. But as we said earlier, all the sample application executables have the same basic configuration. If you would like more help with configuration, you can also read the Configuration by Example section that appears later in this chapter.

However, it is crucial that you are very comfortable with the details presented in Step 6 of the Installation chapter in the eXtropia Applications Guide discussed in Appendix A: Further References.

In particular, you should understand:

[ TOC ]


The Configuration Preamble

Like all eXtropia applications, the application executable (eg address_book.cgi) begins with a preamble. The details of the preamble are explained in Chapter 3 so we won't go over them here. Of course, 99.9% of the time, you will never need to modify this part anyway. So donít get too nervous if the code looks unfamiliar.

Following the preamble are the configurations for the ten major components used by this application.

The following figure shows the configuration hierarchy for the application:

Let's take a look at each type of configuration individually.

[ TOC ]


Session and Session Manager Setup

Sessions give the application the ability to remember what has already happened in an application workflow and are necessary because HTTP is stateless. A session manager is a tool that allows you to more easily manage a session.

You can access a detailed discussion of session and session managers in the eXtropia Applications Guide discussed in Appendex A: Further References.

In this application however, they are primarily used to maintain authentication information. The following example shows how the sessions are configured by default.

 
    my @SESSION_PARAMS = (
        -TYPE            => 'File',
        -MAX_ACCESS_TIME => 60 * 20,
        -SESSION_DIR     => './Datafiles/Sessions'
    );
    
    my @SESSION_MANAGER_PARAMS = (
        -TYPE           => 'FormVar',
        -CGI_OBJECT     => $CGI,
        -SESSION_PARAMS => \@SESSION_PARAMS
    );
    my $SESSION_MGR = Extropia::SessionManager->create(@SESSION_MANAGER_PARAMS);
    my $SESSION     = $SESSION_MGR->createSession();

[ TOC ]


Authentication Setup

Authentication allows an application to check a user against a list of valid users in a data source and decide whether or not any given user should have access to perform some function. If you are interested, you can read more about Authentication in the eXtropia Applications Guide discussed in Appendix A: Further References.

The following shows an example of how the authentication variables are configured by default in WebDB:

 
    my @AUTH_USER_DATASOURCE_FIELD_NAMES = qw(
        username
        password
        groups
        firstname
        lastname
        email
    );
    
    my @AUTH_USER_DATASOURCE_PARAMS = (
        -TYPE            => 'File',
        -FIELD_DELIMITER => '|',
        -FIELD_NAMES     => \@AUTH_USER_DATASOURCE_FIELD_NAMES,
        -FILE            => './Datafiles/users.dat'
    );
    
    my @AUTH_ENCRYPT_PARAMS = (
        -TYPE => 'Crypt'
    );
    
    my %USER_FIELDS_TO_DATASOURCE_MAPPING = (
        'auth_username'     => 'username',
        'auth_username'     => 'username',
        'auth_password'     => 'password',
        'auth_firstname'    => 'firstname',
        'auth_lastname'     => 'lastname',
        'auth_groups'       => 'groups',
        'auth_email'        => 'email'
    );
    
    my @AUTH_CACHE_PARAMS = (
        -TYPE           => 'Session',
        -SESSION_OBJECT => $SESSION
    );
        
    my @AUTH_PARAMS = (
        -TYPE                                => 'DataSource',
        -USER_DATASOURCE_PARAMS              => \@AUTH_USER_DATASOURCE_PARAMS,
        -ENCRYPT_PARAMS                      => \@AUTH_ENCRYPT_PARAMS,
        -AUTH_CACHE_PARAMS                   => \@AUTH_CACHE_PARAMS,
        -ADD_REGISTRATION_TO_USER_DATASOURCE => 1,
        -USER_FIELDS_TO_DATASOURCE_MAPPING   => \%USER_FIELDS_TO_DATASOURCE_MAPPING
    );

[ TOC ]


Authentication Manager Setup.

Generally an application never really talks to an authentication object directly. Usually, it talks to an authentication manager. The authentication manager performs all the visible features of authentication such as presenting a registration or login screen to allow the user to register or log on to the application. Authentication managers are discussed further in the eXtropia Applications Guide.

The following example shows an example of how the authentication manager is configured in WebDB by default:

 
    my @AUTH_REGISTRATION_DH_MANAGER_PARAMS = (
        -DATAHANDLERS => [qw(
            Email
            Exists
        )],
        -FIELD_MAPPINGS => {
                'auth_username'     => 'Username',
                'auth_password'     => 'Password',
                'auth_password2'    => 'Confirm Password',
                'auth_firstname'    => 'First Name',
                'auth_lastname'     => 'Last Name',
                'auth_email'        => 'E-Mail Address'
        },
        -IS_FILLED_IN => [
                    'auth_username',
                    'auth_firstname',
                    'auth_lastname',
                    'auth_email'
        ],
        -IS_EMAIL => [
                    'auth_email'
        ],
        -UNTAINT_EMAIL => [
                    'auth_email'
        ]
    );
    
    my @USER_FIELDS = (qw(
        auth_username
        auth_password
        auth_groups
        auth_firstname
        auth_lastname
        auth_email
    ));
                
    my %USER_FIELD_NAME_MAPPINGS = (
        'auth_username'  => 'Username',
        'auth_password'  => 'Password',
        'auth_group'     => 'Groups',
        'auth_firstname' => 'First Name',
        'auth_lastname'  => 'Last Name',
        'auth_email'     => 'E-Mail'
    );
                
    my %USER_FIELD_TYPES = (
        -USERNAME_FIELD => 'auth_username',
        -PASSWORD_FIELD => 'auth_password',
        -GROUP_FIELD    => 'auth_groups'
    );
          
    my @AUTH_MANAGER_PARAMS = (
        -TYPE                => 'CGI',
        -SESSION_OBJECT      => $SESSION,
        -AUTH_VIEWS          => './Apps/Extropia/MLMViews/CGIViews.pm',
        -VIEW_LOADER         => $VIEW_LOADER,
        -AUTH_PARAMS         => \@AUTH_PARAMS,
        -CGI_OBJECT          => $CGI,
        -ALLOW_REGISTRATION  => 1,
        -ALLOW_USER_SEARCH   => 1,
        -USER_SEARCH_FIELD   => 'auth_email',
        -GENERATE_PASSWORD   => 0,
        -DEFAULT_GROUPS      => 'normal',
        -ADMIN_EMAIL_FROM    => 'you@yourdomain.com',
        -ADMIN_EMAIL_ADDRESS => 'you@yourdomain.com',
        -USER_FIELDS         => \@USER_FIELDS,
        -USER_FIELD_TYPES    => \%USER_FIELD_TYPES,
        -EMAIL_REGISTRATION_TO_ADMIN              => 0,
        -DISPLAY_REGISTRATION_AGAIN_AFTER_FAILURE => 1,
        -USER_FIELD_NAME_MAPPINGS                 => \%USER_FIELD_NAME_MAPPINGS,
        -AUTH_REGISTRATION_DH_MANAGER_PARAMS      => 
                \@AUTH_REGISTRATION_DH_MANAGER_PARAMS
    );

[ TOC ]


Data Handler Manager Setup

As we have gone over in the eXtropia Applications Guide, data handlers perform a number of data filtering and validation functions on incoming form data. Data handler managers manage multiple types of data handlers in a way that makes it simple to perform many handling functions within an application in only a few lines of code.

In this application there are two forms that must be handled:

  • The Add New Entry Form

    This form allows users to add records. This view is defined in the file Views/WebDB/AppName/AddRecordView.pm.

  • The Modify Entry Form

    This form provides a simple interface through which to modify records. This view is defined in the file Views/WebDB/AppName/ModifyRecordView.pm.

An example of how WebDb (specifically addressbook.cgi) is configured by default for HTML form validation is shown below:

 
    my @ADD_FORM_DHM_CONFIG_PARAMS = (
        -TYPE         => 'CGI',
        -CGI_OBJECT   => $CGI,
        -DATAHANDLERS => [qw(
            Email
            Exists
            HTML
            )],
        -ESCAPE_HTML_TAGS => [qw(
            fname
            lname
            email
            category
            phone
            comments
            )],
        -IS_EMAIL => [qw(
            email
            )],
        -IS_FILLED_IN => [qw(
            category
            fname
            lname
            email
            )]
    );
    
    my @MODIFY_FORM_DHM_CONFIG_PARAMS = (
        -TYPE         => 'CGI',
        -CGI_OBJECT   => $CGI,
        -DATAHANDLERS => [qw(
            Email
            Exists
            HTML
        )],
        -ESCAPE_HTML_TAGS => [qw(
            fname
            lname
            email
            category
            phone
            comments
        )],
        -IS_EMAIL => [qw(
            email
        )],
        -IS_FILLED_IN => [qw(
            category
            fname
            lname
            email
        )]
    );

Note that the fields used in the data handler manager configuration relate specifically to the NAME values on the forms. Thus, the data handlers will expect to have a user-supplied value coming from HTML form elements such as:

 
    <INPUT TYPE = "TEXT" NAME = "email">

Notice that the email NAME corresponds to the name used in the -IS_EMAIL, -IS_FILLED_IN, and -ESCAPE_HTML_TAGS data handler rules.

[ TOC ]


Data Source Setup

As you might imagine, the core feature of the application is the data source itself. The data source contains all of the data being managed. As such, we use an Extropia::DataSource. The setup of this module is discussed in further detail in the eXtropia Applications Guide.

The following is an example of how the data source is configured by default in news.cgi (one of the apps that comes with the WebDB package).

 
    my @DATASOURCE_FIELD_NAMES = qw(
        record_id
        subject
        abstract
        full_text
        username_of_poster
        group_of_poster
    );
    
    my $INPUT_WIDGET_DEFINITIONS = {
        subject => [
            -DISPLAY_NAME => 'Subject',
            -TYPE         => 'textfield',
            -NAME         => 'subject',
            -DEFAULT      => '',
            -SIZE         => 30,
            -MAXLENGTH    => 80
        ],
        abstract => [
            -DISPLAY_NAME => 'Abstract',
            -TYPE         => 'textfield',
            -NAME         => 'abstract',
            -DEFAULT      => '',
            -SIZE         => 30,
            -MAXLENGTH    => 80
        ],
        full_text => [
            -DISPLAY_NAME => 'Full Text',
            -TYPE         => 'textarea',
            -NAME         => 'full_text',
            -DEFAULT      => '',
            -ROWS         => 6,
            -COLS         => 30
        ]
    };
    
    my @INPUT_WIDGET_DISPLAY_ORDER = qw(
        subject
        abstract
        full_text
    );
    
    my @DATASOURCE_CONFIG_PARAMS = (
        -TYPE            => 'File',
        -FILE            => './Datafiles/webdb.dat',
        -FIELD_DELIMITER => '|',
        -FIELD_NAMES     => \@DATASOURCE_FIELD_NAMES,
        -FIELD_TYPES     => {
            item_id => 'auto'
        },
    );

[ TOC ]


Mail Setup

One of the most important features of the application is its ability to send email event notifications. Specifically, the application sends three types of emails:

  • Add Event Notifications

    The application administrator may receive a notification email that includes the details of the addition.

  • Delete Event Notifications

    The application administrator may receive a notification email that includes the details of the deletion.

  • Modify Event Notification

    The application administrator may receive a notification email that includes the details of the modification.

Thus, you are going to have to configure an Extropia::Mail driver to perform the mailings. Mail driver configuration is discussed in further detail in the eXtropia Applications Guide. The following example shows how mail is configured on WebDB by default.

 
    my @MAIL_CONFIG_PARAMS = (
        -TYPE => 'Sendmail'
    );
    
    my @EMAIL_DISPLAY_FIELDS = qw(
        category
        fname
        lname
        phone
        email
        comments
    );
    
    my @DELETE_EVENT_MAIL_SEND_PARAMS = (
        -FROM     => 'you@yourdomain.com',
        -TO       => 'you@yourdomain.com',
        -SUBJECT  => 'WebDB Delete'
    );
    
    my @ADD_EVENT_MAIL_SEND_PARAMS = (
        -FROM     => 'you@yourdomain.com',
        -TO       => 'you@yourdomain.com',
        -SUBJECT  => 'WebDB Addition'
    );
    
    my @MODIFY_EVENT_MAIL_SEND_PARAMS = (
        -FROM     => 'you@yourdomain.com',
        -TO       => 'you@yourdomain.com',
        -SUBJECT  => 'WebDB Modification'
    );

WARNING: If you have completed the mail configuration but your application is not mailing, you might check to make sure you have enabled mailing in the @APPLICATION_SETUP array. Remember that you must set -SEND_EMAIL_ON_ADD_FLAG, -SEND_EMAIL_ON_DELETE_FLAG, and -SEND_EMAIL_ON_MODIFY_FLAG to 1 if you want the application to actually mail the user or administrator respectively.

NOTE: If you are wondering how to change the body of the email, check out the AddEventEmailView.pm, ModifyEventEmailView.pm, and DeleteEventEmailView.pm files in the webdb/Views/Extropia/WebDB directory as well as the Look-and-Feel section later in this chapter and the Look-and-Feel chapter of the eXtropia Application Guide.

[ TOC ]


Log Setup

It is possible that you will also wish to maintain a log of errors, accesses and miscellaneous actions. Because of this, the application uses Extropia::Log. The configuration of Extropia::Log is discussed in further detail in the eXtropia Applications Guide.

 
    my @LOG_CONFIG_PARAMS = ( 
        -TYPE             => 'File',
        -LOG_FILE         => './Datafiles/webdb.log',
        -LOG_ENTRY_SUFFIX => '|' . _generateEnvVarsString() . '|',
        -LOG_ENTRY_PREFIX => 'WebDB|'
    );
    sub _generateEnvVarsString {
        my @env_values;
        
        my $key;
        foreach $key (keys %ENV) {
            push (@env_values, "$key=" . $ENV{$key});
        }
        return join ("\|", @env_values);
    }

Note that the _generateEnvVarsString() method is also discussed in the eXtropia Applications Guide under the section discussing the Log configuration.

[ TOC ]


View Setup

Views define the application's user interface. You can find all the views for this application in the webdb/Views/eXtropia directory. For example, if you want to modify the way the Add Record form looks for the News example application, you would edit the file webdb/Views/Extropia/WebDB/News/AddRecordView.pm.

The following is a list of the views and their descriptions for WebDB in the webdb/Views/Extropia/WebDB/AppName:

The template views stored in webdb/Views/Extropia/StandardTemplates are listed below:

The authentication manager views are stored in the webdb/Views/Extropia/AuthManager directory and are listed below (CGIViews.pm).

  • CGIViews.pm

    Defines all the views required for CGI-based authentication.

The default configuration for the views in WebDB, specifically projectmanager.cgi, are shown below:

 
    my @VALID_VIEWS = qw(
        AddRecordView
        BasicDataView
        DetailsView
        BottomFrameView
        FrameView
        ModifyRecordView
        TopFrameView
    );
    
    my @ROW_COLOR_RULES = (
        {'status' => [qw(Requested 99CC99)]}, 
        {'status' => [qw(In-Process CC9999)]},
        {'status' => [qw(Delivered CC9999)]}
    );
    
    my @FIELD_COLOR_RULES = (
        {'project_size' => [qw(Large BLUE)]}, 
        {'project_size' => [qw(Small ORANGE)]}
    );
    
    my @VIEW_DISPLAY_PARAMS = (
        -INPUT_WIDGET_DEFINITIONS   => $INPUT_WIDGET_DEFINITIONS,
        -INPUT_WIDGET_DISPLAY_ORDER => \@INPUT_WIDGET_DISPLAY_ORDER,
        -ROW_COLOR_RULES         => \@ROW_COLOR_RULES,
        -FIELD_COLOR_RULES       => \@FIELD_COLOR_RULES,
        -CGI_OBJECT              => $CGI,
        -COLOR_FOR_EVEN_ROWS     => 'E5E5E5',
        -COLOR_FOR_ODD_ROWS      => 'FFFFFF',
        -APPLICATION_LOGO        => 'web_db_logo.gif',
        -APPLICATION_LOGO_HEIGHT => '63',
        -APPLICATION_LOGO_WIDTH  => '225',
        -APPLICATION_LOGO_ALT    => 'WebDB Demo',
        -HEADER_BG_COLOR         => '000000',
        -HEADER_FONT_COLOR       => 'FFFFFF',
        -TABLE_BG_COLOR_1        => '6699CC',
        -TABLE_BG_COLOR_2        => 'E5E5E5',
        -DOCUMENT_ROOT_URL       => '/',
        -IMAGE_ROOT_URL          => '/images',
        -SCRIPT_DISPLAY_NAME     => 'Project Tracker',
        -SCRIPT_NAME             => 'project_tracker.cgi',
        -PAGE_BACKGROUND_COLOR   => 'FFFFFF',
        -PAGE_BACKGROUND_IMAGE   => 'none defined',
        -PAGE_LINK_COLOR         => 'FFFFFF',
        -PAGE_ALINK_COLOR        => 'FFFFFF',
        -PAGE_VLINK_COLOR        => 'FFFFFF',
        -PAGE_FONT_COLOR         => '000000',
        -PAGE_FONT_SIZE          => '-1',
        -PAGE_FONT_FACE          => 'VERDANA, ARIAL, HELVETICA, SANS-SERIF',
        -EMAIL_DISPLAY_FIELDS    => \@EMAIL_DISPLAY_FIELDS,
        -HOME_VIEW               => 'BasicDataView',
        -FIELD_NAME_MAPPINGS   => {
            status              => 'Status',
            project_name        => 'Project Name',
            project_size        => 'Project Size',
            estimated_man_hours => 'Est. Man Hours',
            developer_name      => 'Developer',
            client_name         => 'Client',
            comments            => 'Comments'
        },
        -DISPLAY_FIELDS        => [qw(
            status
            project_name
            project_size
            estimated_man_hours
            developer_name
            client_name
            comments
        )],
        -SELECTED_DISPLAY_FIELDS        => [qw(
            status
            project_name
            developer_name
            client_name
            comments
        )]
    );

    NOTE: There is no need to put email-related views in the @VALID_VIEWS list because the email-related views are not actually displayed to a web browser They are just used to help compose email bodies. Similarly, you need not list views that are only called by other views in the @VALID_VIEWS list because the views called by other views are considered safe since they may not be specified from the web browser.

Notice in particular the use of the color configuration parameters. These two view parameters can be used to color any row or field that matches the search criteria. For example, in the code above, you can see that if any row has a status field equal to Requested, the row will be colored green (99CC99). Likewise, any row that has the keyword Large in the project_size field will be colored blue.

[ TOC ]


Filter Setup

Filters are used to modify the contents of views before they are sent to the web browser. In other words, filters are components that transform the output of a view based on a set of logic. For example, using an SSI Include filter allows you to execute SSI Include commands inside of your HTML view output. You can find out more about filters and how they are set up in the eXtropia Applications Guide.

 
    my @CENSOR_FILTER_CONFIG_PARAMS = (
        -TYPE => 'Censor',
        -WORDS_TO_FILTER => [qw(
            proprietary
        )]
    );
     
    my @VIEW_FILTERS_CONFIG_PARAMS = (
        \@CENSOR_FILTER_CONFIG_PARAMS
    );

[ TOC ]


Application Setup

Finally, we are ready to put all the configuration variables into the application object configuration! This parameter contains references to all the configuration parameters that we just discussed. It also defines several application flags and values. It is this mega-package of configuration parameters that is sent to the application object (WebDB.pm) to initialize the application at run-time.

Let's look at the parameters in greater detail:

  • -ADD_EMAIL_BODY_VIEW

    This optional parameter specifies the view used to generate the body of the email sent to the administrator in the case of an add event.

  • -ADD_EVENT_MAIL_SEND_PARAMS

    This optional parameter specifies a set of mail parameters used to define the details of the emails sent on add events if -SEND_EMAIL_ON_ADD_FLAG has been set to 1. By default, all mail parameters must define -TO, -FROM, -SUBJECT, and -BODY.

    However, optionally, they may define -CC, -BCC, -REPLY_TO, and -ATTACH. Note that the actual body of the email sent is defined by the view defined by AddEventEmailView.pm.

  • -ADD_FORM_DH_MANAGER_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::DataHandler configuration parameters. This configuration is used to handle the Addition form.

  • -ADD_FORM_VIEW_NAME

    This required parameter specifies the name of the view used to generate the Add form. The value is used primarily in error handling functions in which the application needs to return the user to the last form they were on.

  • -ALLOW_ADDITIONS_FLAG

    This optional parameter specifies whether or not to allow additions. If set to 0, the application will not allow users to add entries.

  • -ALLOW_DELETIONS_FLAG

    This optional parameter specifies whether or not to allow deletions. If set to 0, the application will not allow users to delete entries.

  • -ALLOW_MODIFICATIONS_FLAG

    This optional parameter specifies whether or not to allow modifications. If set to 0, the application will not allow users to modify entries.

  • -AUTH_MANAGER_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::AuthManager configuration parameters. The AuthManager will control authentication within your application. Whenever the authenticate() method is called, the user will have to provide a valid username and password. However, because the application stores valid logon results in the session object, they must only do so once in the application lifecycle.

  • -BASIC_DATA_VIEW_NAME

    This required parameter specifies the name of the view used to generate the Basic Data view.

  • -CGI_OBJECT

    This required parameter contains a reference to a CGI object (instantiated from Lincoln Stein's CGI.pm library). The CGI object will contain all of the data supplied by the user. It is used in several locations including the add, modify, and delete routines as well as in several views that must implement stickiness.

  • -DATASOURCE_CONFIG_PARAMS

    This required parameter contains a reference to Extropia::DataSource configuration parameters. By default, all eXtropia applications use a File-based data source for cross-platform reasons. However, you can easily use this parameter to specify any other eXtropia data source type.

  • -DEFAULT_MAX_RECORDS_PER_PAGE

    This optional parameter specifies how many records to display per page. If it is not specified, it is set to 10 by default.

  • -DEFAULT_SORT_FIELD1

    This optional parameter specifies a field within the data source to sort on when data is returned from a search. Note that the field name should correspond to one of the fields specified in @DATASOURCE_FIELD_NAMES. For example if the first name field was specified and a data source search returned three names, Michael, and Anthony and Jeremy, the rows would be sorted to be Anthony, Jeremy, and Michael.

  • -DEFAULT_SORT_FIELD2

    This optional parameter specifies a secondary field within the data source to sort on when data is returned from a search. Note that the field name should correspond to one of the fields specified in @DATASOURCE_FIELD_NAMES.

    For example if the first name field were specified as -SORT_FIELD1 and the last name field were specified as -SORT_FIELD2, and a data source search returned three names Michael Chopek, and Michael Budash and Jeremy Horland, the rows would be sorted to be Jeremy Horland, Michael Budash, and Michael Chopek. Notice that Budash comes before Chopek as last name is specified as a secondary sort order to the first name.

  • -DEFAULT_VIEW_NAME

    This required parameter specifies what view the application should display. Note that because of how it is defined, this parameter may be overridden with a view parameter specified in the incoming HTTP stream. Views are explained in more detail in the eXtropia Applications Guide.

  • -DELETE_EMAIL_BODY_VIEW

    This optional parameter specifies the view used to generate the body of the email sent to the administrator in the case of a delete event.

  • -DELETE_EVENT_MAIL_SEND_PARAMS

    This optional parameter specifies a set of mail parameters used to define the details of the emails sent on delete events if -SEND_EMAIL_ON_DELETE_FLAG has been set to 1. By default, all mail parameters must define -TO, -FROM, -SUBJECT, and -BODY. However, optionally, they may define -CC, -BCC, -REPLY_TO, and -ATTACH. Note that the actual body of the email sent is defined by the view defined by DeleteEventEmailView.pm.

  • -DELETE_FORM_DH_MANAGER_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::DataHandler configuration parameters. This configuration is used to handle the Delete form.

  • -DELETE_FORM_VIEW_NAME

    This required parameter specifies the name of the view used to generate the Delete form. The value is used primarily in error handling functions in which the application needs to return the user to the last form they were on.

  • -LOG_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::Log configuration parameters. The log will record important events such as additions, modifications, deletions, as well as notable errors such as attempts to load invalid views.

  • -MAIL_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::Mail configuration parameters. The parameter is optional because a data source administrator may not wish to implement any emailing workflow. To turn off emailing, you must set -SEND_EMAIL_ON_DELETE_FLAG, -SEND_EMAIL_ON_DELETE_FLAG, and -SEND_EMAIL_ON_DELETE_FLAG equal to 0.

  • -MODIFY_EMAIL_BODY_VIEW

    This optional parameter specifies the view used to generate the body of the email sent to the administrator in the case of a modify event.

  • -MODIFY_EVENT_MAIL_SEND_PARAMS

    This optional parameter specifies a set of mail parameters used to define the details of the emails sent on modify events if -SEND_EMAIL_ON_MODIFY_FLAG has been set to 1. By default, all mail parameters must define -TO, -FROM, -SUBJECT, and -BODY. However, optionally, they may define -CC, -BCC, -REPLY_TO, and -ATTACH. Note that the actual body of the email sent is defined by the view defined by ModifyEventEmailView.pm.

  • -MODIFY_FORM_DH_MANAGER_CONFIG_PARAMS

    This optional parameter contains a reference to Extropia::DataHandler configuration parameters. This configuration is used to handle the Modification Form.

  • -MODIFY_FORM_VIEW_NAME

    This required parameter simply specifies the name of the view used to generate the Modify Form. The value is used primarily in error handling functions in which the application needs to return the user to the last form they were on.

  • -REQUIRE_AUTH_FOR_ADDING_FLAG

    This optional parameter specifies whether or not users must authenticate in order to add to the database. If it is set to 1, users must authenticate. If set to 0, users can add without logging on.

  • -REQUIRE_AUTH_FOR_DELETING_FLAG

    This optional parameter specifies whether or not users must authenticate in order to delete from the database. If it is set to 1, users must authenticate. If set to 0, users can delete without logging on.

  • -REQUIRE_AUTH_FOR_MODIFYING_FLAG

    This optional parameter specifies whether or not users must authenticate in order to modify the database. If it is set to 1, users must authenticate. If set to 0, users can modify without logging on.

  • -REQUIRE_AUTH_FOR_SEARCHING_FLAG

    This optional parameter specifies whether or not users must authenticate in order to search the database. If it is set to 1, users must authenticate. If set to 0, users can search without logging on.

  • -REQUIRE_MATCHING_USERNAME_FOR_MODIFICATIONS_FLAG

    This optional parameter specifies whether the user who originally added a record will be the only user allowed to modify the record. It is is set to 1, only the user may modify the record.

  • -REQUIRE_MATCHING_USERNAME_FOR_MODIFICATIONS_FLAG

    This optional parameter specifies whether the user who originally added a record will be the only user allowed to delete the record. It is is set to 1, only the user who created the entry may delete the record.

  • -SEND_EMAIL_ON_ADD_FLAG

    This optional parameter determines whether or not the application should send an email when it performs a successful addition. If it is set to 0, no emails will be sent. If it is set to 1, and you have properly defined -MAIL_CONFIG_PARAMS and -ADD_EVENT_MAIL_SEND_PARAMS, the application will send mail. By default, the parameter is set to 0 .

  • -SEND_EMAIL_ON_DELETE_FLAG

    This optional parameter determines whether or not the application should send an email when it performs a successful deletion. If it is set to 0, no emails will be sent. If it is set to 1, and you have properly defined -MAIL_CONFIG_PARAMS and -DELETE_EVENT_MAIL_SEND_PARAMS, the application will send mail. By default, the parameter is set to 0.

  • -SEND_EMAIL_ON_MODIFY_FLAG

    This optional parameter determines whether or not the application should send an email when it performs a successful modification. If it is set to 0, no emails will be sent. If it is set to 1, and you have properly defined -MAIL_CONFIG_PARAMS and -MODIFY_EVENT_MAIL_SEND_PARAMS, the application will send mail. By default, the parameter is set to 0.

  • -SESSION_OBJECT

    This optional parameter contains a reference to a Session object. Session is used to store information about the user in an otherwise stateless environment. Most notably, authentication information is stored in the session object so that the application can keep track of which users have logged in successfully and not bother them with logon screens every time new form is submitted.

  • -VALID_VIEWS

    This is a required parameter that contains a reference to a list of valid views. For security reasons, this application will not display any view that has not specifically been named in this parameter. Thus, if you add a new view, you will have to add it to this parameter.

  • -VIEW_DISPLAY_PARAMS

    This required parameter contains a reference to a set of view parameters. This parameter specifies the content that is published to all views. Views selectively subscribe to whatever elements of this parameter that they are interested in. If you wish to change something about how the data is displayed, it is a good chance that you will use this parameter rather than modifying the application code.

  • -VIEW_FILTERS_CONFIG_PARAMS

    This optional parameter contains a reference to a list of Extropia::Filter configuration parameters.

  • -VIEW_LOADER

    This required parameter contains a reference to a view loader.

[ TOC ]


Step 7: Modify Application Look-and-Feel

As we mentioned earlier, all views are located in the webdb/Views/eXtropia directory. If you want to change the way the user interface looks, you will have to edit one or more of these files. The eXtropia Applications Guide provides a detailed discussion of how to edit views. This guide also contains a section on typical configuration by example configuration changes which includes a typical change to the views.

[ TOC ]


Step 8: Run the Application

Running the application is a simple matter of pointing your web browser at the newly installed application executable using a URL such as:

http://www.mydomain.com/cgi-bin/webdb/app_name.cgi

Hopefully, the application will come up and you can begin to test it. If however, you receive an error message, you should consult Steps 8 and 9 in the Installation chapter of the eXtropia Applications Guide for help with debugging the problem.

[ TOC ]


Step 9: Debug the Application

Debugging can be quite an intensive process. Fortunately, there is an entire section to teach you how to debug CGI applications (and eXtropia applications in particular) in the eXtropia Applications Guide discussed in Appendix A: Further References.

[ TOC ]


Step 10: Review the Security Checklist

Have you read the section on security in the eXtropia Applications Guide? If not, you should do so now! Otherwise, here is the checklist (taken from this guide) of issues you should review before making this application available to the public.

  1. Add index.html files to all directories.

  2. Change default filenames.

  3. Use the .cgi extension for administrative or data files.

  4. Move all files (except for executables) out of the web document tree altogether.

  5. Set permissions correctly.

  6. Quarantine writable files.

  7. Revoke CGI rights except where required.

  8. Disable SSI if possible.

  9. Do not add insecure code.

  10. Don't disable built-in Perl security.

  11. Stay informed by returning regularly to http://www.extropia.com/ or by adding yourself to the mailing list at register@extropia.com.

[ TOC ]


Step 11: Test the Application

Before you actually go live with your application, you should also submit the application to thorough testing by a selected group of beta users. Some testing recommendations are presented in the eXtropia Applications Guide as a starting point.

[ TOC ]


Step 12: Register the Application

Finally, to make sure that you stay up to date with bug fixes, enhancements, and security bulletins, register your installation with eXtropia by sending an email to register@extropia.com. Include the URL of your installation in the email if you wish it to be added to the list of example sites.

Also, if you have made significant additions, please submit your ideas and solutions to the Radical Hacks Page (http://www.extropia.com/hacks/) at eXtropia by sending an email to hacks@extropia.com.

[ TOC ]


Installation Summary

Congratulations! You have installed an eXtropia application. If this is your first one, feel heartened by the fact that since all the applications are similar, installing your second one will be far easier.

But before you move on to your next one, perhaps you would like to learn more about how the application works. Alternatively, perhaps you want to modify the application in ways more drastic than simply changing the configuration parameters.

If that is the case, you will want to read the next half of this chapter. However, if you are not into the techie bits, you can just stop here. If you are happy with the application, there is no great need to spend time with the code. We realize that you may have better things to do, like run an online business! [ TOC ]


[ TOC ]


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