view release on metacpan or  search on metacpan

lib/CGI/Framework.pm  view on Meta::CPAN

If you supplied the fatal_error_email key, you must also supply this key and/or the smtp_host key.  If you'd like to deliver the mail using sendmail, supply this key with a value of the fully qualified path to your sendmail binary.

=item sessions_dir

B<OPTIONAL>

This key should have a scalar value holding a directory name where the session files will be stored.  If not supplied, a suitable temporary directory will be picked from the system.

Note: You may not supply this if you supply the sessions_mysql_dbh key.

=item sessions_mysql_dbh

B<OPTIONAL>

This key should have a value that's a MySQL DBH (DataBase Handle) instance created with the DBI and DBD::Mysql modules.  If supplied then the session data will be stored in the mysql table instead of text files.  For more information on how to prepar...

Note: You may not supply this if you supply the sessions_dir key.

=item sessions_serializer_default

B<OPTIONAL>

This key should be set to true if you wish to use the default serialization method for your sessions.  This requires the perl module Data::Dumper.  For more information refer to the L<CGI::Session::Serialize::Default> documentation.

Note: You may not supply this if you supply the sessions_serializer_storable or sessions_serializer_freezethaw keys.

=item sessions_serializer_freezethaw

B<OPTIONAL>

This key should be set to true if you wish to use the FreezeThaw serialization method for your sessions.  This requires the perl module FreezeThaw.  For more information refer to the L<CGI::Session::Serialize::FreezeThaw> documentation.

Note: You may not supply this if you supply the sessions_serializer_default or sessions_serializer_storable keys.

=item sessions_serializer_storable

B<OPTIONAL>

This key should be set to true if you wish to use the Storable serialization method for your sessions.  This requires the perl module Storable.  For more information refer to the L<CGI::Session::Serialize::Storable> documentation.

Note: You may not supply this if you supply the sessions_serializer_default or sessions_serializer_freezethaw keys.

=item smtp_from

B<OPTIONAL>

If your mail server supplied in smtp_host is picky about the "from" address it accepts emails from, set this key to a scalar email address value.  If not set, the email address 'cgiframework@localhost' will be set as the from-address.

=item smtp_host

B<OPTIONAL>

If you supplied the fatal_error_email key, you must also supply this key and/or the sendmail key.  If you'd like to deliver the mail using direct SMTP transactions (and have Net::SMTP installed), supply this key with a value of the hostname of the ma...

If your mailserver is picky about the "from" address it accepts mail from, you should also supply the smtp_from key when using this key, otherwise 'cgiframework@localhost' will be supplied as the from address.

=item templates_dir

B<OPTIONAL>

This key should have a scalar value holding a directory name which contains all the template files.  If not supplied, it will be guessed based on the local directory.

=item valid_languages

B<OPTIONAL>

This key should have an arrayref value.  The array should contain all the possible language tags you've used in the templates.  Refer to the "INTERNATIONALIZATION AND LOCALIZATION" section.  You must set this key if you wish to also set the "maketext...

=back

=item initialize_cgi_framework(%hash)

Just like the above new() constructor, except used in the function-based approach instead of the object-oriented approach.

=back

=head1 METHODS / FUNCTIONS

=over 4

=item add_error($scalar [, @array ] )

This method accepts a scalar error and adds it to the list of errors that will be shown to the client.  It should only be called from a validate_templatename() subroutine for each error found during validating the form.  This will cause the dispatch(...

If you specified the "valid_languages" and the "maketext_class_name" keys to the initializer, the error message you give to this method will be localized to the user's preferred language (or the default language) before being showed to the user.  Ref...

=item assert_form(@array)

This method accepts an array of scalar values.  Each element will be checked to make sure that it has been submitted in the just-submitted form and has a true value.  If any elements aren't found or have a false value, the missinginfo template is sho...

=item assert_session(@array)

Just like the assert_form() method, except it checks the values against the session instead of the submitted form.

=item clear_session

This method deletes all the previously-stored values using the session() or remember() methods.

=item dispatch

This method is the central dispatcher.  It calls validate_templatename on the just-submitted template, checks to see if any errors were added with the add_error() method.  If any errors were added, re-sends the client the previous template, otherwise...

=item finalize

This method undefs some internal references that prevent the object from being destroyed.  It's called automatically for you when show_template() is done or if there's a fatal error, so there is usually no need to call it manually.

This method exit()s when done - it does not return.

=item form($scalar)

This method accepts an optional scalar as it's first argument, and returns the value associated with that key from the just-submitted form from the client.  If no scalar is supplied, returns all entries from the just-submitted form.

=item get_cgi_object

Returns the underlying CGI object.  To be used if you'd like to do anything fancy this module doesn't provide methods for, such as processing extra cookies, etc...

=item get_cgi_session_object

Returns the underlying CGI::Session object.  To be used if you'd like to do anything fancy this module doesn't provide methods for.

=item html($scalar, $scalar)

lib/CGI/Framework.pm  view on Meta::CPAN

				}
				if (!$errorsent) {
					print "Content-type: text/html\n\n<h1>The following fatal error occurred:</h1><p><pre>$error</pre>\n";
				}

				#
				# Now try to send the fatal error email
				#
				if (!$emailsent && $para{"fatal_error_email"} && $para{"sendmail"}) {
					eval {
						open(SMH, "| $para{sendmail} -t -i") || die "Failed to open pipe to sendmail: $!\n";
						print SMH "From: " . ($para{"smtp_from"} || 'cgiframework@localhost') . "\n";
						print SMH "To: ", (ref($para{"fatal_error_email"}) eq "ARRAY" ? join(",", @{ $para{"fatal_error_email"} }) : $para{"fatal_error_email"}), "\n";
						print SMH "Subject: Fatal Error\n";
						print SMH "X-CGI-Framework-Method: sendmail $para{sendmail}\n";
						print SMH "X-CGI-Framework-REMOTE-ADDR: $ENV{REMOTE_ADDR}\n";
						print SMH "X-CGI-Framework-PID: $$\n";
						print SMH "\n";
						print SMH "The following fatal error occurred:\n\n$error\n";
						close(SMH);
					};
					$emailsent = 1 if !$@;
				}
				if (!$emailsent && $para{"fatal_error_email"} && $para{"smtp_host"}) {
					eval {
						require Net::SMTP;
						my $smtp = Net::SMTP->new($para{"smtp_host"}) || die "Could not create Net::SMTP object: $@\n";
						$smtp->mail($para{"smtp_from"} || 'cgiframework@localhost') || die "Could not send MAIL command: $@\n";
						$smtp->recipient(ref($para{"fatal_error_email"}) eq "ARRAY" ? @{ $para{"fatal_error_email"} } : $para{"fatal_error_email"}) || die "Could not send RECIPIENT command: $@\n";
						$smtp->data("X-CGI-Framework-Method: Net::SMTP $para{smtp_host}\nX-CGI-Framework-REMOTE-ADDR: $ENV{REMOTE_ADDR}\nX-CGI-Framework-PID: $$\n\nThe following fatal error occurred:\n\n$error") || die "Could not send DATA command: $@\n";
						$smtp->quit();
					};
					$emailsent = 1 if !$@;
				}

				#
				# Finally cleanup cruft:
				#
				$self->finalize();
			}
		);
	}

	#
	# Some initial setup
	#
	$para{_html} = {};

	#
	# We set some defaults if unsupplied
	#
	$para{valid_languages} ||= [];
	$para{callbacks_namespace} ||= (caller)[0] || "main";
	if (!$para{cookie_name}) {
		$para{cookie_name} = "sessionid_$ENV{SCRIPT_NAME}";
		$para{cookie_name} =~ s/[^0-9a-z]//gi;
	}
	if (!$para{sessions_mysql_dbh} && !$para{sessions_dir}) {

		#
		# They didn't supply any sessions stuff, so let's take a guess at some directories for file-based storage:
		#
		foreach (qw(/tmp /var/tmp c:/tmp c:/temp c:/windows/temp)) {
			if (-d $_) {
				$para{sessions_dir} = $_;
				last;
			}
		}
	}
	if (!$para{templates_dir}) {
		foreach (qw(./templates ../templates)) {
			if (-d $_) {
				$para{templates_dir} = $_;
				last;
			}
		}
	}
	if (!$para{sessions_serializer_default} && !$para{sessions_serializer_storable} && !$para{sessions_serializer_freezethaw}) {
		$para{sessions_serializer_default} = 1;
	}

	#
	# Now we do sanity checking
	#
	ref $para{valid_languages} eq "ARRAY" || croak "valid_languages must be an array ref";
	if ($para{"maketext_class_name"}) {
		@{ $para{valid_languages} } || croak "valid_languages must be set to at least one language to specify the maketext_class_name key";
	}
	$para{sessions_dir} && $para{sessions_mysql_dbh} && croak "Only one of sessions_dir and sessions_mysql_dbh may be supplied";
	if ($para{sessions_dir}) {

		#
		# Supplied (or determined) file-based sessions storage
		#
		-e $para{sessions_dir} && !-d $para{sessions_dir} && croak "$para{sessions_dir} exists but is not a directory";
		-d $para{sessions_dir} || mkdir($para{sessions_dir}, 0700) || croak "Failed to create $para{sessions_dir}: $!";
		-w $para{sessions_dir} || croak "$para{sessions_dir} is not writable by me";
	}
	elsif ($para{sessions_mysql_dbh}) {

		#
		# Supplied mysql-based sessions storage
		# Should be a reference to mysql object - but I'll just make sure it's *a* reference to something
		#
		ref($para{sessions_mysql_dbh}) || croak "Invalid sessions_mysql_dbh supplied";
	}
	else {
		croak "Neither sessions_dir or sessions_mysql_dbh were supplied, and could not automatically determine a suitable sessions_dir";
	}
	if ((grep { $para{$_} } qw(sessions_serializer_default sessions_serializer_storable sessions_serializer_freezethaw)) > 1) {
		croak "Only one of sessions_serializer_default, sessions_serializer_storable and sessions_serializer_freezethaw may be supplied";
	}
	$para{templates_dir}                  || croak "templates_dir must be supplied";
	-d $para{templates_dir}               || croak "$para{templates_dir} does not exist or is not a directory";
	-f "$para{templates_dir}/errors.html" || croak "Templates directory $para{templates_dir} does not contain the mandatory errors.html template";
	$para{initial_template}               || croak "initial_template not supplied";
	if ($para{log_filename}) {
		open(FH, ">>$para{log_filename}") || croak "Log filename $para{log_filename} is not writeable by me: $@";
		close(FH);
	}
	if ($para{output_filter}) {