package PXSQL::XCGI;
#------------------------------------------------------------------
# Project  : Perl XSQL
# Name     : XCGI.pm
# Author   : Gilles Darold, gilles __AT__ darold __DOT__ net
# Copyright: Copyright (c) 2001 Gilles Darold
# Function : CGI to XML writer
# Usage    : See documentation.
#------------------------------------------------------------------
# Version control :
# $Id$
#------------------------------------------------------------------
use vars qw($VERSION);

use strict;

$VERSION = '1.0';

# This hash is use to emulate CGI parameter persistance through XML/XSL
# files. You can add all CGI parameters that should always be used into
# your Web application, if you use session for example it's a
# better choice to insert the corresponding CGI parameters here
# than repeat it for all templates into the configuration file. 
%PXSQL::XCGI::PARAM = (
	'template'=>''
);


=head1 NAME

XCGI - A perl module for writing CGI parameters into a XML data file


=head1 SYNOPSIS


    use PXSQL::XCGI;

    # Create a new instance of the XCGI perl OO module
    my $xcgi = new PXSQL::XCGI('./cgi_param.lst');

    my $cgi_data = $xsql->getData($cgi, $template);


=head1 DESCRIPTION

This module is a simple writer of CGI parameters into a XML data file.
It has no interrest outside the perl xsql program.

The written data have the following format:

    <CGI>
	<param_name>value</param_name>
	...
    </CGI>

So if you need them into your XSL file they are provide like describe above.


=head1 METHODS

=head2 new

A new instance of the perl module must be call as follow:

	new PXSQL::XCGI( config_file_pathi, noheader )

The config_file_path is the path to a file that must have the follwing format:

    template_alias:param1=default_value:paramN=default_value:

Default value will be used if the CGI parameter is not set.

The parameter noheader is a boolean to specify if the end tag of the
XSQL header must be written. Default will write this footer. It consist
in the following string:

	</PXSQL>

If you provide your own XML header, it means that you have set noheader to 1
when at creation time of the PXSQL::XSQL instance you must also set it to 1
here.


=cut

sub new
{
	my $this = shift ;

	my $class = ref($this) || $this ;
	my $self = {} ;
	bless $self, $class;
	$self->_init(@_) || return undef;

	return $self;
}


=head2 _init

This method init the XCGI perl module instance and load the entire content
of the configuration file into a single hash %CGI_PARAM.

=cut

sub _init
{
	my ($self, $conf, $noheader) = @_;

	$self->{noheader} = $noheader || '';
	$self->{CGI_PARAM} = ();

	return if (!$conf);

	local (*CONF) = '';
	open(CONF, "$conf") or die "XCGI error: can't load file $conf, $!\n";
	while (my $l = <CONF>) {
		chomp($l);
		next if ( ($l =~ /[\s\t]*#/) || ($l eq "") );
		my @arry = split(/:/, $l);
		my $alias = shift(@arry);
		foreach my $p (@arry) {
		       my ($key , $val) = split(/=/, $p);
		       $self->{CGI_PARAM}{$alias}{$key} = $val if ($key);
		}
	}
	close CONF;

	$self->{output} = "<CGI>\n";

}


=head2 getData

This method insert into the XML data all CGI parameters
set into the main HASH %CGI_PARAM for the given template.

It also append all CGI parameters set into the hash of default
CGI parameters (see _set_xml_default_param).

=cut

sub getData
{
        my ($self, $cgi, $template) = @_;

	# Insert default CGI parameters
        $self->{output} .= &_set_xml_default_param($cgi);

	# Insert wanted CGI parameters
	if (exists $self->{CGI_PARAM}{$template}) {
		foreach (keys %{$self->{CGI_PARAM}{$template}}) {
			if ($cgi->param($_) ne "") {
				$self->{output} .= "\t<$_>" . $cgi->param($_) . "</$_>\n";
			} elsif ($self->{CGI_PARAM}{$template}{$_} ne "") {
				$self->{output} .= "\t<$_>$self->{CGI_PARAM}{$template}{$_}</$_>\n";
			} else {
				$self->{output} .= "\t<$_ />\n";
			}
		}
	}

	$self->{output} .= "</CGI>\n";
	$self->{output} .= "</PXSQL>" if (!$self->{noheader});

        return $self->{output};

}

=head2 _set_xml_default_param

This method is call internally to insert into the XML data the default
CGI parameters set into the main HASH %PXSQL::XCGI::PARAM.

=cut

sub _set_xml_default_param
{
	my ($cgi) = @_;

	my $ret = "";
	foreach (keys %PXSQL::XCGI::PARAM) {
		if ($cgi->param($_) ne "") {
			$ret .= "\t<$_>" . $cgi->param($_) . "</$_>\n";
		} elsif ($PXSQL::XCGI::PARAM{$_} ne '') {
			$ret .= "\t<$_>$PXSQL::XCGI::PARAM{$_}</$_>\n";
		} else {
			$ret .= "\t<$_ />\n";
		}
	}
	$ret .= "";

	return $ret;
}


1;

__END__


=head1 AUTHOR

Gilles Darold <gilles __AT__ darold __DOT__ net>

=head1 COPYRIGHT

Copyright (c) 2001 Gilles Darold - All rights reserved

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

=head1 SEE ALSO

L<PXSQL::XSQL>

=cut