Installation Guide

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

Use a program such as WINZIP to unpack.

[ TOC ]

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:

• The application executables (eg. address_book.cgi) should have read and execute permission (r-xr-xr-x).

• The Datafiles directory and all sub-directories of the Datafiles directory, should have read, write and execute permissions (rwxrwxrwx).

• Files within the Datafiles directory and all files within sub-directories of the Datafiles directory, should have read and write permission (rw-rw-rw).

• All modules, views, and the application object (WebDB.pm) should have read-only permission (r--r--r--).

• The Modules directory and all its subdirectories as well as the View directory and all its subdirectories should have read and execute privileges (r-xr-x r-x).

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 ]

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 ]

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:

• How configuration works.

• How to modify configuration parameters.

• How to debug configuration modification errors.

[ TOC ]

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.

• Session

• Session Management

• Authentication

• Authentication Manager

• DataHandlerManager

• DataSource

• Mailing

• Logging

• View

• Filter

The following figure shows the configuration hierarchy for the application:

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

[ TOC ]

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 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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

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:

• AddRecordView.pm

  Defines the user interface for the Add Record form.

• BasicDataView

  Defines the user interface for the main application frame in which searches are displayed in using HTML tables.

• ModifyRecordView.pm

  Defines the user interface for the Modify Record form.

• DetailsView.pm

  Defines the user interface that presents the full record details

• AddEventEmailView.pm

  Defines the contents of the email body sent after add events

• ModifyEventEmailView.pm

  Defines the contents of the email body sent after modify events

• DeleteEventEmailView.pm

  Defines the contents of the email body sent after delete events

• RecordSetDetailsFooterView.pm

  Defines the footer for the record set detail (eg an ending </TABLE> tag).

• SearchBoxView.pm

  Defines the user interface for the search box shown on the top of the BasicDataView.

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

• BottomFrameView.pm

  Defines the bottom application frame.

• ErrorDisplayView.pm

  Defines the error reporting user interface.

• FrameView.pm

  Defines the base application frame.

• TopFrameView.pm

  Defines the top application frame.

• PageTopView

  Defines the page header

• PageBottomView

  Defines the page footer

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]

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 ]