MAN page from Old RedHat 5.X perl-5.004-4.i386.rpm

CGI::Push

Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index

NAME

CGI::Push - Simple Interface to Server Push

SYNOPSIS

    use CGI::Push qw(:standard);

    do_push(-next_page=>\&next_page,            -last_page=>\&last_page,            -delay=>0.5);

    sub next_page {        my($q,$counter) = @_;        return undef if $counter >= 10;        return start_html('Test'),               h1('Visible'),"\n",               "This page has been called ", strong($counter)," times",               end_html();      }

     sub last_page {         my($q,$counter) = @_;         return start_html('Done'),                h1('Finished'),                strong($counter),' iterations.',                end_html;     }

DESCRIPTION

CGI::Push is a subclass of the CGI object created by CGI.pm. It isspecialized for server push operations, which allow you to createanimated pages whose content changes at regular intervals.

You provide CGI::Push with a pointer to a subroutine that will drawone page. Every time your subroutine is called, it generates a newpage. The contents of the page will be transmitted to the browserin such a way that it will replace what was there beforehand. Thetechnique will work with HTML pages as well as with graphics files, allowing you to create animated GIFs.

USING CGI::Push

CGI::Push adds one new method to the standard CGI suite, do_push().When you call this method, you pass it a reference to a subroutinethat is responsible for drawing each new page, an interval delay, andan optional subroutine for drawing the last page. Other optionalparameters include most of those recognized by the CGI header()method.

You may call do_push() in the object oriented manner or not, as youprefer:

    use CGI::Push;    $q = new CGI::Push;    $q->do_push(-next_page=>\&draw_a_page);

        -or-

    use CGI::Push qw(:standard);    do_push(-next_page=>\&draw_a_page);

Parameters are as follows:

-next_page

    do_push(-next_page=>\&my_draw_routine);

This required parameter points to a reference to a subroutine responsible fordrawing each new page. The subroutine should expect two parametersconsisting of the CGI object and a counter indicating the numberof times the subroutine has been called. It should return thecontents of the page as an array of one or more items to print. It can return a false value (or an empty array) in order to abort theredrawing loop and print out the final page (if any)

    sub my_draw_routine {        my($q,$counter) = @_;        return undef if $counter > 100;        return start_html('testing'),               h1('testing'),               "This page called $counter times";    }

-last_page

This optional parameter points to a reference to the subroutineresponsible for drawing the last page of the series. It is calledafter the -next_page routine returns a false value. The subroutineitself should have exactly the same calling conventions as the-next_page routine.

-type

This optional parameter indicates the content type of each page. Itdefaults to ``text/html''. Currently, server push of heterogeneousdocument types is not supported.

-delay

This indicates the delay, in seconds, between frames. Smaller delaysrefresh the page faster. Fractional values are allowed.

If not specified, -delay will default to 1 second

-cookie, -target, -expires

These have the same meaning as the like-named parameters inCGI::header().

INSTALLING CGI::Push SCRIPTS

Server push scripts must be installed as no-parsed-header (NPH)scripts in order to work correctly. On Unix systems, this is mostoften accomplished by prefixing the script's name with ``nph-''. Recognition of NPH scripts happens automatically with WebSTAR and Microsoft IIS. Users of other servers should see their documentationfor help.

CAVEATS

This is a new module. It hasn't been extensively tested.

AUTHOR INFORMATION

be used and modified freely, but I do request that this copyrightnotice remain attached to the file. You may modify this module as youwish, but if you redistribute a modified version, please attach a notelisting the modifications you have made.

Address bug reports and comments to:lsteinAATTgenome.wi.mit.edu

BUGS

This section intentionally left blank.

This document was created byman2html,using the manual pages.