home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _a540429040325eadc044efe2fcd17956 < prev    next >
Text File  |  2000-03-23  |  14KB  |  358 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>CGI::Screen - Perl extension for easy creation of multi screen CGI scripts</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> CGI::Screen - Perl extension for easy creation of multi screen CGI scripts</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#warning">WARNING</A></LI>
  25.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#the constructor new">The constructor <CODE>new</CODE></A></LI>
  29.         <LI><A HREF="#adding screens">Adding Screens</A></LI>
  30.         <LI><A HREF="#moving between screens">Moving between screens</A></LI>
  31.         <LI><A HREF="#the callbacks">The callbacks</A></LI>
  32.         <LI><A HREF="#authentication">Authentication</A></LI>
  33.         <LI><A HREF="#customizing the title">Customizing the Title</A></LI>
  34.         <LI><A HREF="#customizing the headline">Customizing the Headline</A></LI>
  35.         <LI><A HREF="#customizing the trailer">Customizing the Trailer</A></LI>
  36.         <LI><A HREF="#multiple forms">Multiple Forms</A></LI>
  37.         <LI><A HREF="#non html screens">Non HTML screens</A></LI>
  38.         <LI><A HREF="#keeping parameter values">Keeping parameter values</A></LI>
  39.     </UL>
  40.  
  41.     <LI><A HREF="#bugs">BUGS</A></LI>
  42.     <LI><A HREF="#author">AUTHOR</A></LI>
  43.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  44.     <LI><A HREF="#acknowledgements">ACKNOWLEDGEMENTS</A></LI>
  45.     <LI><A HREF="#copyright">Copyright</A></LI>
  46. </UL>
  47. <!-- INDEX END -->
  48.  
  49. <HR>
  50. <P>
  51. <H1><A NAME="name">NAME</A></H1>
  52. <P>CGI::Screen - Perl extension for easy creation of multi screen CGI scripts</P>
  53. <P>
  54. <HR>
  55. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  56. <UL>
  57. <LI>Linux</LI>
  58. <LI>Solaris</LI>
  59. <LI>Windows</LI>
  60. </UL>
  61. <HR>
  62. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  63. <PRE>
  64.   use CGI::Screen;
  65.   use vars qw(@ISA);
  66.   @ISA = qw(CGI::Screen);</PRE>
  67. <PRE>
  68.   my $query = __PACKAGE__->new;</PRE>
  69. <PRE>
  70.   $query->dispatch;</PRE>
  71. <P>
  72. <HR>
  73. <H1><A NAME="warning">WARNING</A></H1>
  74. <P>This is <STRONG>alpha</STRONG> software. User visible changes can happen any time.</P>
  75. <P>
  76. <HR>
  77. <H1><A NAME="description">DESCRIPTION</A></H1>
  78. <P><STRONG>CGI::Screen</STRONG> is a subclass of <CODE>CGI</CODE> which allows the <CODE>esay(TM)</CODE>
  79. creation of simple multi screen CGI scripts. By 'multi screen' I mean
  80. scripts which present different screens to the user when called with
  81. different parameters. This is the common case for scripts linking to
  82. themselves.</P>
  83. <P>To use <STRONG>CGI::Screen</STRONG>, you have to subclass it. For each screen you
  84. want to present to the user, you must create a method
  85. <EM>screen_name</EM><CODE>screen_</CODE>. This method has to produce the HTML code for
  86. the screen. CGI::Screen does generate HTTP headers and an HTML
  87. framework for you. The HTML framework already contains the <CODE>FORM</CODE>
  88. tags.  You can customize the HTTP headers and the HTML framework by 
  89. providing callback methods.</P>
  90. <P>CGI::Screen keeps track of the CGI parameters used in your screen and
  91. passes old parameters which are not used in the current screen.</P>
  92. <P>It highjacks the parameters <CODE>screen_</CODE>* to dispatch the different
  93. screens the script implements. The <CODE>screen_user</CODE> and <CODE>screen_passwd</CODE>
  94. fields are used if you enable the builtin simple authentication.  In
  95. general you should advice your HTTP server to do authentication. But
  96. sometimes it is convenient to check the authentication at the script
  97. level. Especially if you do not have access to your server's
  98. configuration.</P>
  99. <P>
  100. <H2><A NAME="the constructor new">The constructor <CODE>new</CODE></A></H2>
  101. <P>If the first parameter of <CODE>new</CODE> is the string <CODE>-screen</CODE> the second
  102. argument must be a hash reference specifying the options for the
  103. subclass. Other parameters are passed to the constructor of <CODE>CGI</CODE>.</P>
  104. <DL>
  105. <DT><STRONG><A NAME="item_%2Ddont_cut_loops"><CODE>-dont_cut_loops</CODE></A></STRONG><BR>
  106. <DD>
  107. Normaly the history of pages will not be extended if the current page is
  108. the same as the last page. So looping on a page will not change the
  109. result of the <CODE>last_screen</CODE> method. If the option <A HREF="#item_%2Ddont_cut_loops"><CODE>-dont_cut_loops</CODE></A>
  110. is provided and true, the page will recorded twice. A third visit will
  111. be interpreted as jump back to the first visit.
  112. <P><EM>That sounds weird. Will have to figure out a way to recognize back
  113. jumps independent of the history.</EM></P>
  114. <P></P></DL>
  115. <P>
  116. <H2><A NAME="adding screens">Adding Screens</A></H2>
  117. <P>All applications should provide a <STRONG>main</STRONG> screen by defining a method
  118. <CODE>main_screen</CODE>. This method is called if no (existing) screen is
  119. specified in the parameters. The method is called with three
  120. arguments: The query object, the screen name and the screen title
  121. (More precisely the third parameter, if present, is the text on the
  122. button or anchor which caused the jump to this page).</P>
  123. <P>So the minimal application looks like this:</P>
  124. <PRE>
  125.   use CGI::Screen;
  126.   use vars qw(@ISA);
  127.   @ISA = qw(CGI::Screen);
  128. </PRE>
  129. <PRE>
  130.  
  131.   my $query = __PACKAGE__->new;</PRE>
  132. <PRE>
  133.  
  134.   $query->dispatch;</PRE>
  135. <PRE>
  136.  
  137.   sub main_screen {
  138.     my $query = shift;</PRE>
  139. <PRE>
  140.  
  141.     print $query->p('This is the Main Screen');
  142.   }</PRE>
  143. <P>That is not too exciting. Let us add a second screen and allow
  144. navigation between the screens:</P>
  145. <PRE>
  146.   sub main_screen {
  147.     my $query = shift;
  148. </PRE>
  149. <PRE>
  150.  
  151.     print
  152.       $query->p('This is the Main Screen'),
  153.       $query->goto_screen('second', 'Another Screen');
  154.   }
  155.   sub second_screen {
  156.     my $query = shift;</PRE>
  157. <PRE>
  158.  
  159.     print
  160.       $query->p('This is the Other Screen'),
  161.       $query->goto_screen('main', 'Back to Main Screen');</PRE>
  162. <PRE>
  163.   }</PRE>
  164. <P>
  165. <H2><A NAME="moving between screens">Moving between screens</A></H2>
  166. <P>Use the method <CODE>goto_screen</CODE> to produce a button for switching to
  167. another screen.  You can also produce an anchor instead of a button by
  168. calling <CODE>link_to_screen</CODE> instead of <CODE>goto_screen</CODE>. You may pass
  169. additional parameters to encode:</P>
  170. <PRE>
  171.     for my $docid (keys %score) {
  172.       print $query->link_to_screen('display', $title{$docid},
  173.                                    'docid' => $docid,
  174.                                    'score' => $score{$docid});
  175.     }</PRE>
  176. <P>For convenience, CGI::Screen keeps track of the last screen for you so
  177. that you can link to the previous page. Note that only the last seven
  178. screens are saved:</P>
  179. <PRE>
  180.   my $screen = $query->last_screen;
  181.   print
  182.     $query->p("You came from screen $screen. Press "),
  183.     $query->goto_screen($query->last_screen),
  184.     $query->p(" to go back");</PRE>
  185. <P><CODE>last_screen</CODE> returns screen name and title in list context and
  186. screen name in scalar context. Do not use the CGI parameters
  187. <CODE>screen_last_*</CODE> since they are changed before you can get hold of
  188. them <CODE>;-P</CODE></P>
  189. <P>
  190. <H2><A NAME="the callbacks">The callbacks</A></H2>
  191. <P>All callbacks are called with three arguments: The query object, the
  192. screen name and the screen title (= button/anchor text). Callbacks
  193. should return a string.</P>
  194. <DL>
  195. <DT><STRONG><A NAME="item_application"><CODE>application</CODE></A></STRONG><BR>
  196. <DD>
  197. The <A HREF="#item_application"><CODE>application</CODE></A> method returns a string which is used
  198. in the default <A HREF="#item_title"><CODE>title</CODE></A> and <A HREF="#item_headline"><CODE>headline</CODE></A> callbacks. The Default method
  199. returns the string <CODE>"CGI::Screen Test"</CODE> and should definitely be
  200. overwritten by your application.
  201. <P></P>
  202. <DT><STRONG><A NAME="item_title"><CODE>title</CODE></A></STRONG><BR>
  203. <DD>
  204. The result of the method is used in the HTTP header and in the default
  205. headline. It defaults to the <EM>application</EM>.
  206. <P></P>
  207. <DT><STRONG><A NAME="item_headline"><CODE>headline</CODE></A></STRONG><BR>
  208. <DD>
  209. The <A HREF="#item_headline"><CODE>headline</CODE></A> method should return a chunk of HTML code to start the
  210. Screen. It defaults to the <EM>title</EM> enclosed in <CODE>H1</CODE> tags.
  211. <P></P></DL>
  212. <P>
  213. <H2><A NAME="authentication">Authentication</A></H2>
  214. <P>To enable password authentication, define a method
  215. <CODE>check_auth_user</CODE>. The dispatcher will call the method with the user
  216. and password entered by the user. The method should return true if the
  217. authentication succeeded and false otherwise. The dispatcher will
  218. present the <CODE>login_screen</CODE> if the authentication failed.</P>
  219. <PRE>
  220.   sub check_auth_user {
  221.     my ($query, $user, $passwd) = @_;</PRE>
  222. <PRE>
  223.     $user eq 'pfeifer';
  224.   }</PRE>
  225. <P>For IP address based authentication define the method
  226. <CODE>check_auth_ip</CODE>.</P>
  227. <PRE>
  228.   sub check_auth_ip {
  229.     my ($query, $ipaddr) = @_;</PRE>
  230. <PRE>
  231.    $ipaddr =~ /^(193\.96\.65\.|139\.4\.36\.)/;
  232.   }</PRE>
  233. <P>If you do not like the default login screen, overwrite with your own
  234. <CODE>login_screen</CODE>. Use the CGI parameters <CODE>screen_user</CODE> and
  235. <CODE>screen_passwd</CODE>.</P>
  236. <P>
  237. <H2><A NAME="customizing the title">Customizing the Title</A></H2>
  238. <P>You may provide a custom <A HREF="#item_title"><CODE>title</CODE></A> method to generate a title for your
  239. screens.</P>
  240. <PRE>
  241.   sub title {
  242.     my ($query, $screen)  = shift;
  243. </PRE>
  244. <PRE>
  245.  
  246.     $query->application . ': ' . $screen;
  247.   }</PRE>
  248. <P>
  249. <H2><A NAME="customizing the headline">Customizing the Headline</A></H2>
  250. <P>You may provide a custom <A HREF="#item_headline"><CODE>headline</CODE></A> method to generate a HTML chunk
  251. to start your screens.</P>
  252. <PRE>
  253.   sub headline { $_[0]->h1(title(@_)) }</PRE>
  254. <P>You should overwrite the <A HREF="#item_application"><CODE>application</CODE></A> method if you use the default
  255. title and headline.</P>
  256. <PRE>
  257.   sub application { 'CGI::Screen Test' }</PRE>
  258. <P>
  259. <H2><A NAME="customizing the trailer">Customizing the Trailer</A></H2>
  260. <P>For a custom Trailer, define the <CODE>trailer</CODE> method.</P>
  261. <PRE>
  262.   sub trailer {
  263.     my ($query, $screen)  = shift;
  264. </PRE>
  265. <PRE>
  266.  
  267.     "End of Screen $screen";
  268.   }</PRE>
  269. <P>
  270. <H2><A NAME="multiple forms">Multiple Forms</A></H2>
  271. <P>If you want to have multiple forms on one screen, call the method
  272. <CODE>new_form</CODE>.</P>
  273. <PRE>
  274.   sub multi_screen {
  275.      my $query = shift;</PRE>
  276. <PRE>
  277.      print
  278.        $query->p('This is the Main Screen'),
  279.        $query->textfield('foo'),
  280.        $query->goto('First'),
  281.        $query->new_form,
  282.        $query->textfield('foo'),
  283.        $query->goto('Second');
  284.   }</PRE>
  285. <P>
  286. <H2><A NAME="non html screens">Non HTML screens</A></H2>
  287. <P>You can create non HTML screens by defining a <EM>name</EM><CODE>_data</CODE> method
  288. instead of a <name><CODE>_screen</CODE> method. For <CODE>data</CODE> screens you have
  289. to generate HTTP headers yourself.</P>
  290. <PRE>
  291.   sub gif_data {
  292.     my $query = shift;
  293. </PRE>
  294. <PRE>
  295.  
  296.     print $query->header(
  297.                          -type    => 'image/gif',
  298.                          -status  => '200 OK',
  299.                          -expires => '+120s',
  300.                         );
  301.     my $font  = $query->param('font');
  302.     my $w     = GD::Font->$font()->width;
  303.     my $h     = GD::Font->$font()->height;
  304.     my $im    = GD::Image->new((length($query->param('foo'))+2)*$w,$h);
  305.     my $white = $im->colorAllocate(255,255,255);
  306.     my $red   = $im->colorAllocate(255,0,0);
  307.     my $black = $im->colorAllocate(0,0,0);
  308.     $im->transparent($white);
  309.     $im->arc(8,8,5,5,0,360,$red);
  310.     $im->string(GD::Font->$font(),10,0,$query->param('foo'),$black);
  311.     print $im->gif;
  312.   }</PRE>
  313. <P>
  314. <H2><A NAME="keeping parameter values">Keeping parameter values</A></H2>
  315. <P>CGI::Screen keeps track of the CGI parameters used in the current
  316. form. It simply looks at the first parameter in any call to a CGI
  317. method.  If the first parameter is <CODE>-name</CODE>, the second parameter is
  318. marked as <EM>used parameter</EM>.  CGI::Screen passed all current parameter
  319. values not used in hidden fields or in the query string of an
  320. anchor. So do not use old style CGI calls to bypass this mechanism or
  321. you will end up with multiple values for the parameters.</P>
  322. <P>If you want to get rid of a parameter, you must explicitly call the
  323. <A HREF="../../../lib/Pod/perlfunc.html#item_delete"><CODE>delete</CODE></A> method of CGI.</P>
  324. <P>
  325. <HR>
  326. <H1><A NAME="bugs">BUGS</A></H1>
  327. <P>Support for importing from CGI.pm is incomplete.</P>
  328. <P>
  329. <HR>
  330. <H1><A NAME="author">AUTHOR</A></H1>
  331. <P>Ulrich Pfeifer <<EM><A HREF="mailto:pfeifer@wait.de">pfeifer@wait.de</A></EM>></P>
  332. <P>
  333. <HR>
  334. <H1><A NAME="see also">SEE ALSO</A></H1>
  335. <P>The <CODE>CGI(3)</CODE> manual and the demo CGI script <EM>eg/screen</EM> included in the
  336. distribution.</P>
  337. <P>
  338. <HR>
  339. <H1><A NAME="acknowledgements">ACKNOWLEDGEMENTS</A></H1>
  340. <P>I wish to thank Andreas Koenig <EM><A HREF="mailto:koenig@kulturbox.de">koenig@kulturbox.de</A></EM> for the
  341. fruitful discussion about the design of this module.</P>
  342. <P>
  343. <HR>
  344. <H1><A NAME="copyright">Copyright</A></H1>
  345. <P>The <STRONG>CGI::Screen</STRONG> module is Copyright (c) 1997,1998 Ulrich
  346. Pfeifer. Germany.  All rights reserved.</P>
  347. <P>You may distribute under the terms of either the GNU General Public
  348. License or the Artistic License, as specified in the Perl README file.</P>
  349. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  350. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  351. <STRONG><P CLASS=block> CGI::Screen - Perl extension for easy creation of multi screen CGI scripts</P></STRONG>
  352. </TD></TR>
  353. </TABLE>
  354.  
  355. </BODY>
  356.  
  357. </HTML>
  358.