| 0 | |
# $Id: XMLApplication.pm,v 1.19 2004/03/10 17:55:00 c102mk Exp $
|
| 1 | |
|
| 2 | 0 |
package CGI::XMLApplication;
|
| 3 | 1 |
|
| 4 | 2 |
# ################################################################
|
| 5 | |
# $Revision: 1.19 $
|
| 6 | |
# $Author: c102mk $
|
| 7 | 3 |
#
|
| 8 | |
# (c) 2001 Christian Glahn <christian.glahn@uibk.ac.at>
|
| 9 | |
# All rights reserved.
|
|
4 |
# (c) 2001 Christian Glahn <phish@CPAN.org>
|
| 10 | 5 |
#
|
| 11 | 6 |
# This code is free software; you can redistribute it and/or
|
| 12 | 7 |
# modify it under the same terms as Perl itself.
|
|
| 32 | 27 |
|
| 33 | 28 |
# ################################################################
|
| 34 | 29 |
|
| 35 | |
$CGI::XMLApplication::VERSION = "1.1.3";
|
|
30 |
$CGI::XMLApplication::VERSION = "1.1.4";
|
| 36 | 31 |
|
| 37 | 32 |
# ################################################################
|
| 38 | 33 |
# general configuration
|
|
| 483 | 478 |
content deliverment.
|
| 484 | 479 |
|
| 485 | 480 |
As well CGI::XMLApplication is designed to support project management
|
| 486 | |
on code level. The class allows to split web applications into several
|
|
481 |
on code level. The class allows splitting web applications into several
|
| 487 | 482 |
simple parts. Through this most of the code stays simple and easy to
|
| 488 | 483 |
maintain. Throughout the whole runtime of a script
|
| 489 | 484 |
CGI::XMLApplication tries to keep the application stable. As well a
|
|
| 519 | 514 |
or less redundant code. Since most CGI-scripts are waiting for
|
| 520 | 515 |
B<events>, which is usually the code abstraction of a click of a
|
| 521 | 516 |
submit button or an image, CGI::XMLApplication implements a simple
|
| 522 | |
event system, that allows to keep event related code as separated as
|
| 523 | |
possible.
|
| 524 | |
|
| 525 | |
Therefore final application class is not ment to have a constructor
|
|
517 |
event system, that keeps event related code separated from other events.
|
|
518 |
|
|
519 |
Therefore, a final application class is not meant to have a constructor
|
| 526 | 520 |
anymore. All functionality should be encapsulated into implicit or
|
| 527 | 521 |
explicit event handlers. Because of a lack in Perl's OO implementation
|
| 528 | 522 |
the call of a superclass constructor before the current constructor
|
|
| 687 | 681 |
to any kind of display type, there should be no need to override this
|
| 688 | 682 |
function. One can pass a context hash or context object, to pass external
|
| 689 | 683 |
or prefetched information to the application. This context will be
|
| 690 | |
available and acessable in all events and most extra functions.
|
|
684 |
available and accessible in all events and most extra functions.
|
| 691 | 685 |
|
| 692 | 686 |
This function does all event and serialization related work. As well
|
| 693 | 687 |
there is some validation done as well, so catched events, that are not
|
|
| 755 | 749 |
|
| 756 | 750 |
To make it clear: If CGI::XMLApplication throws a panic, the
|
| 757 | 751 |
application is broken, not completely implemented or stylesheets are
|
| 758 | |
missing or broken. Application panics are ment for debugging purposes
|
| 759 | |
and to avoid I<Internal Server Errors>. They are B<not> ment as a
|
|
752 |
missing or broken. Application panics are meant for debugging purposes
|
|
753 |
and to avoid I<Internal Server Errors>. They are B<not> meant as a
|
| 760 | 754 |
replacement of a propper error handling!
|
| 761 | 755 |
|
| 762 | 756 |
But how does CGI::XMLApplication know about the correct event handler?
|
|
| 776 | 770 |
|
| 777 | 771 |
Each event has a single Parameter, the context. This can be an unblessed
|
| 778 | 772 |
hash reference or an object, where the user can store whatever needed.
|
| 779 | |
This context is useful to pass scriptwide data between callbacks and
|
|
773 |
This context is useful to pass scriptwide data between callbacks and
|
| 780 | 774 |
event functions around. The callback is even available and useable if
|
| 781 | 775 |
the script does not initialize the application context as earlier shown
|
| 782 | 776 |
in the program flow chart.
|
|
| 895 | 889 |
=item event_default
|
| 896 | 890 |
|
| 897 | 891 |
This event is called as a fallback mechanism if CGI::XMLApplication
|
| 898 | |
did not receive a stylesheet id by an other event handler; for example
|
| 899 | |
if no event matched.
|
|
892 |
did not receive a stylesheet id by another event handler, for example
|
|
893 |
if no event is matched.
|
| 900 | 894 |
|
| 901 | 895 |
=back
|
| 902 | 896 |
|
|
| 993 | 987 |
or remove cookies. The keys of the hash must be the same as the named
|
| 994 | 988 |
parameters of CGI.pm's header method. One does not need to care about
|
| 995 | 989 |
the output of these headers, this is done by CGI::XMLApplication
|
| 996 | |
automaticly.
|
|
990 |
automatically.
|
| 997 | 991 |
|
| 998 | 992 |
The content type of the returned data is usually not required to be
|
| 999 | 993 |
set this way, since the XSLT processor knows about the content type,
|
|
| 1004 | 998 |
If the B<getStylesheet> is implemented the CGI::XMLApplication will
|
| 1005 | 999 |
assume the returned value either as a filename of a stylesheet or as a
|
| 1006 | 1000 |
XML DOM representation of the same. If Stylesheets are stored in a
|
| 1007 | |
file accessable from the , one should set the common path for the
|
| 1008 | |
stylesheets and let B<CGI::XMLApplication> do the parsing job.
|
|
1001 |
folder accessible for the the web-server, a common path for the
|
|
1002 |
stylesheets should be set and B<CGI::XMLApplication> will initiate
|
|
1003 |
the parsing job.
|
| 1009 | 1004 |
|
| 1010 | 1005 |
In cases the stylesheet is already present as a string (e.g. as a
|
| 1011 | 1006 |
result of a database query) one may pass this string directly to
|
|
| 1017 | 1012 |
If none of these stylesheet selectors succeeds the I<Stylesheet
|
| 1018 | 1013 |
missing> panic code is thrown. If the parsing of the stylesheet XML
|
| 1019 | 1014 |
fails I<Stylesheet not available> is thrown. The latter case will also
|
| 1020 | |
give some informations where the stylesheet selection failed.
|
|
1015 |
provide details where the stylesheet selection failed.
|
| 1021 | 1016 |
|
| 1022 | 1017 |
B<selectStylesheet()> has to return a valid path/filename for the
|
| 1023 | 1018 |
stylesheet requested.
|
| 1024 | 1019 |
|
| 1025 | 1020 |
=item getXSLTParameter()
|
| 1026 | 1021 |
|
| 1027 | |
This function allows to pass a set of parameters to XML::LibXSLT's xsl
|
|
1022 |
This function helps passing parameters to XML::LibXSLT's xsl
|
| 1028 | 1023 |
processor. The function needs only to return a hash and does not need
|
| 1029 | 1024 |
to encode the parameters.
|
| 1030 | 1025 |
|
| 1031 | 1026 |
The function is the last callback called before the XSLT processing is
|
| 1032 | |
done.
|
|
1027 |
started.
|
| 1033 | 1028 |
|
| 1034 | 1029 |
=back
|
| 1035 | 1030 |
|
| 1036 | 1031 |
=head2 Flow Control
|
| 1037 | 1032 |
|
| 1038 | |
Besides the sendEvent() function does CGI::XMLApplication provide to
|
| 1039 | |
other functions that allow to controll the flow of the application.
|
|
1033 |
Besides the sendEvent() function, CGI::XMLApplication provides
|
|
1034 |
two additional functions for controlling the flow of the application.
|
| 1040 | 1035 |
|
| 1041 | 1036 |
These two functions are related to the XML serialization and have not
|
| 1042 | 1037 |
affect to the event handling.
|
| 1043 | 1038 |
|
| 1044 | 1039 |
|
| 1045 | |
=over 4
|
|
1040 |
=over 4
|
| 1046 | 1041 |
|
| 1047 | 1042 |
=item passthru()
|
| 1048 | 1043 |
|
|
| 1064 | 1059 |
function should be used in set rather than get mode. The parameter is
|
| 1065 | 1060 |
interpreted as just described.
|
| 1066 | 1061 |
|
| 1067 | |
If an application sets passthru by itself any external 'passthru'
|
| 1068 | |
parameter will be lost. This is usefull if one likes to avoid, someone
|
| 1069 | |
can fetch the plain (untransformed) XML Data.
|
|
1062 |
If an application sets passthru by itself, any external 'passthru'
|
|
1063 |
parameter will be lost. This is useful if the application requires
|
|
1064 |
access to the plain (untransformed) XML Data.
|
| 1070 | 1065 |
|
| 1071 | 1066 |
|
| 1072 | 1067 |
=item skipSerialization()
|
|
| 1095 | 1090 |
This function searches the query string for a parameter with the
|
| 1096 | 1091 |
passed name. The implementation is "imagesave" meaning there is no
|
| 1097 | 1092 |
change in the code needed, if you switch from input.type=submit to
|
| 1098 | |
input.type=image or vv. The algorithm tests wheter a full name is
|
|
1093 |
input.type=image or vv. The algorithm tests whether a full name is
|
| 1099 | 1094 |
found in the querystring, if not it tries tests for the name expanded
|
| 1100 | 1095 |
by a '.x'. In context of events this function interprets each item
|
| 1101 | 1096 |
part in the query string list as an event. Because of that, the
|
| 1102 | 1097 |
algorithm returns only the first item matched.
|
| 1103 | 1098 |
|
| 1104 | |
If you use the event interface on this function, make sure, the
|
| 1105 | |
HTML-forms pass unique events to the script. This is neccessary to
|
|
1099 |
If you use the event interface with this function, then the
|
|
1100 |
HTML-forms should pass unique events to the script in order to
|
| 1106 | 1101 |
avoid confusing behaviour.
|
| 1107 | 1102 |
|
| 1108 | 1103 |
This function is used by testEvent() so if it is required to change
|
|
| 1112 | 1107 |
|
| 1113 | 1108 |
This a simple error message handler. By default this function will
|
| 1114 | 1109 |
print some information to the client where the application
|
| 1115 | |
failed. While development this is a useful feature on production
|
|
1110 |
failed. During development, this is a useful feature, while on a production
|
| 1116 | 1111 |
system this may pass vunerable informations about the system to the
|
| 1117 | |
outside. To change the default behaviour, one may write his own panic
|
| 1118 | |
method or simply set I<$CGI::XMLApplication::Quiet> to 1. The latter
|
| 1119 | |
still causes the error page but does not send any error message.
|
|
1112 |
clients. To change the default behaviour, I<$CGI::XMLApplication::Quiet>
|
|
1113 |
should get set to 1. This will still show an error page but without
|
|
1114 |
displaying error messages. Alternatively, the panic method can be overloaded.
|
| 1120 | 1115 |
|
| 1121 | 1116 |
The current implementation send the 404 status to the client if any
|
| 1122 | 1117 |
low level errors occour ( e.g. panic levels > -4 aka Application
|
|
| 1172 | 1167 |
=head2 some extra functions for stylesheet handling
|
| 1173 | 1168 |
|
| 1174 | 1169 |
The getStylesheet() function should return either a filename or a
|
| 1175 | |
stringnyfied XSL-DOM. For the firstcase it can be a restriction to
|
| 1176 | |
return the fully qualified path. The following functions allow to set
|
| 1177 | |
the stylesheetpath systemwide.
|
|
1170 |
stringnyfied XSL-DOM. For the first case it can be a restriction to
|
|
1171 |
return the fully qualified path. The following functions help managing
|
|
1172 |
the stylesheetpath, system-wide.
|
| 1178 | 1173 |
|
| 1179 | 1174 |
=over 4
|
| 1180 | 1175 |
|
|
| 1186 | 1181 |
|
| 1187 | 1182 |
This method is for telling the application where the stylesheets can
|
| 1188 | 1183 |
be found. If you keep your stylesheets in the same directory as your
|
| 1189 | |
script -- IMHO a bad idea -- you might leave this untouched.
|
|
1184 |
script you might leave this untouched. However, it is suggested to store
|
|
1185 |
stylesheet files in a directory that is out of reach for client access.
|
| 1190 | 1186 |
|
| 1191 | 1187 |
=item function getStylesheetPath
|
| 1192 | 1188 |
|
|
| 1202 | 1198 |
|
| 1203 | 1199 |
=head1 AUTHOR
|
| 1204 | 1200 |
|
| 1205 | |
Christian Glahn, christian.glahn@uibk.ac.at
|
|
1201 |
Christian Glahn, phish@cpan.org
|
| 1206 | 1202 |
|
| 1207 | 1203 |
=head1 VERSION
|
| 1208 | 1204 |
|
| 1209 | |
1.1.1
|
|
1205 |
1.1.4
|