"new()"

"new()" requires several options, see above for syntax:

• query - this is the CGI.pm query object for this run. Pager will remove it's state-maintaining parameters from the query. They all begin with PAGER_, so just be careful not to use that prefix.
• rows - this is the total number of rows in your dataset. This is needed to provide the next-button, prev-button and page-jump functionality.
• page_size - the number of rows to display at one time.
• get_data_callback - this is a callback that you provide to get the pages of data. It is passed two arguements - the offset and the number of rows in the page. You return an array ref containing array refs of row data. For you DBI-heads, this is very similar to selectall_arrayref() - so similar that for very simple cases you can just pass the result through. Example - this is a sub that returns data from an in-memory array of hash refs.

    my @data = ( 
                 { name => sam, age => 10 },
                 { name => saa, age => 11 },
                 { name => sad, age => 12 },
                 { name => sac, age => 13 },
                 { name => sab, age => 14 },
                 # ...
               );
  
    my $get_data_sub = sub {
       my ($offset, $rows) = @_;
       my @return_array;
  
       for (my $x = 0; $x < $rows; $x++) {
          push(@return_array, [ $data[$offset + $x]{name}, 
                                $data[$offset + $x]{age} 
                              ]
              );
       }
       return \@return_array;
    }
            
    my $pager = HTML::Pager->new(query => $query,
                                 get_data_callback => $get_data_sub,
                                 rows => 100,
                                 page_size => 10
                                );
      

  You can also specify arguements to be passed to your callback function. To do this, call new like:

    HTML::Pager->new(query => $query,
                     get_data_callback => [$get_data_sub, $arg, $arg],
                     rows => 100,
                     page_size => 10
                    );
      

  If you want to use named, rather than numeric TMPL_VARs in your Pager template you can return a ref to an array of hashes rather than arrays. This array of hashes will be passed directly to HTML::Template to fill in the loop data for your paging area.

"new()" supports several optional arguements:

• debug - if set to 1, debugging information is warn()'d during the program run. Defaults to 0.
• template - this is an HTML::Template object to use instead of the auto-generated HTML::Template used in Pager output. It must define the following TMPL_LOOPs and TMPL_VARs. Here's what the default template looks like, to give you an idea of how to change it to suite your purposes:

    <TMPL_VAR NAME="PAGER_JAVASCRIPT">
    <FORM>
    <TABLE BORDER=0 BGCOLOR=#000000 WIDTH=100%>
    <TR><TD><TABLE BORDER=0 WIDTH=100%>
    <TMPL_LOOP NAME="PAGER_DATA_LIST">
      <TR>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_0"></TD>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_1"></TD>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="PAGER_DATA_COL_2"></TD>
        <!--- depends on number of rows in data - so should your replacement! -->
      </TR>
    </TMPL_LOOP>
    <TR><TD BGCOLOR=#DDDDDD COLSPAN=3 ALIGN=CENTER>
      <TMPL_VAR NAME="PAGER_PREV">
      <TMPL_VAR NAME="PAGER_JUMP">
      <TMPL_VAR NAME="PAGER_NEXT">
    </TD></TR>
    </TABLE>
    </TABLE>
    <TMPL_VAR NAME="PAGER_HIDDEN">
    </FORM>
      

  Make sure you include all the TMPL_LOOPs and TMPL_VARs included above. If you get HTML::Template errors about trying to set bad param 'PAGER_BLAH', that probably means you didn't put the 'PAGER_BLAH' variable in your template. You can put extra state-maintaining <INPUT> fields in the paging form - in fact, I think that this is probably required for most real-world uses.

  Optionally you can use named parameters inside PAGER_DATA_LIST, and return an array of hashes to fill them in from get_data_callback. If you did that your template might look like:

    ...
    <TMPL_LOOP NAME="PAGER_DATA_LIST">
      <TR>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="NUMBER"></TD>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="FIRST_NAME"></TD>
        <TD BGCOLOR=#ffffff><TMPL_VAR NAME="LAST_NAME"></TD>
      </TR>
    </TMPL_LOOP>
    ...
      

• persist_vars - Pass a ref to an array of the names of the CGI form parameters you want to store into this fuction, and they will be included in the hidden form data of the pager form.

  This method allows you to have hidden form variables which persist from page to page. This is useful when connecting your pager to some other function (such as a search form) which needs to keep some data around for later use.

  The old $pager->persist_vars() syntax still works but is deprecated.

• column_names - should be set to an array ref containing the names of the columns - this will be used to create column headers. Without this arguement, the columns will have no headers. This option is only useful in very simple cases where all the data is actually in use as columns. Example:

     my $pager = HTML::Pager->new( column_names => [ 'one', 'two' ]);
      

• cell_space_color - this specifies the color of the lines separating the cells. If the default template is mostly OK, except for the color scheme, this will provide a middle ground between the necessity of creating your own Pager template and suffering with bad colors. Example:

     my $pager = HTML::Pager->new( cell_space_color => '#222244' );
      

• cell_background_color - this specifies the background color of each data cell. If the default template is mostly OK, except for the color scheme, this will provide a middle ground between the necessity of creating your own Pager template and suffering with bad colors. Example:

     my $pager = HTML::Pager->new( cell_background_color => '#000000' );
      

• nav_background_color - this specifies the background color of the bottom navigation bar. If the default template is mostly OK, except for the color scheme, this will provide a middle ground between the necessity of creating your own Pager template and suffering with bad colors. Example:

     my $pager = HTML::Pager->new( nav_background_color => '#222244' );
      

• javascript_presubmit - this optional parameter allows you to specify a Javascript function which will be called when a user clicks on one of the Pager navigation buttons, prior to submitting the form. Only if this function returns 'true' will the form be submitted.

  The Pager navigation calls its 'PAGER_set_offset_and_submit()' javascript function when a user clicks the "Next", "Previous" or other page buttons. This normally precludes calling your own javascript submit functions to perform some task.

  Through this hook, you can perform client-side functions, such as form validation, which can modify the form or actually prevent the user from going to the next page. This is particularly useful for enabling some kind of work-flow involving form validation.

   Constructor Example:
  
      my $pager = HTML::Pager->new( 
                     javascript_presubmit => 'last_minute_javascript()' 
                  );
  
  
   HTML Example:
  
      <script language=Javascript>
          function last_minute_javascript() {
              return confirm("Are you sure you want to leave this page?");
          }
      </script>
      

"output()"