source: trunk/lib/PageNumbers.inc.php @ 1

<?php
/**
 * PageNumbers.inc.php
 * Code by Strangecode :: www.strangecode.com :: This document contains copyrighted information
 *
 * The PageNumbers:: class provides a common abstracted interface to the
 * multiple pages features. It sets the various numbers needed to display items
 * on a page, and includes functions for working with these numbers.
 * You must call set setTotalItems(), setPerPage() and setPageNumber() before calling calculate()
 * this the other various values will be set automatically. Then you can call printPerPageLinks,
 * printPageNumbers, etc, and use the various page object properties in your page templates.
 *
 * @author    Quinn Comendant <quinn@strangecode.com>
 * @version   1.61
 */
 
require_once dirname(__FILE__) . '/Prefs.inc.php';

class PageNumbers {
    
    var $total_items;       // Total quantity of items.
    var $total_pages;       // The total number of pages.
    var $current_page = 1;  // Current page number.
    var $first_item;        // The counter for the first item on this page (zero index).
    var $last_item;         // The counter for the last item on this page (zero index).
    var $max_num_links = 9; // The max number of links to show on page (odd numbers look best).
    var $_num_links;        // The number of links to show on page.
    var $_per_page = 25;    // Items per page.

    // Flags to ensure all necessary values have been set before calling calculate().
    var $set_per_page_initialized = false;
    var $set_page_number_initialized = false;
    var $set_total_items_initialized = false;
    
    // These are initialized in the constructor.
    var $per_page_options;
    var $left_arrow;
    var $left_arrow_disabled;
    var $left_dbl_arrow;
    var $left_dbl_arrow_disabled;
    var $right_arrow;
    var $right_arrow_disabled;
    var $right_dbl_arrow;
    var $right_dbl_arrow_disabled;
        
    /**
     * PageNumbers constructor. All arguments are depreciated. Use set* functions instead.
     */
    function PageNumbers()
    {
        // Default options for the quantity per page links.
        $this->per_page_options = array(25, 50, 100, 200);
        
        // Default options for the page number links.
        $this->left_arrow = _("back");
        $this->left_arrow_disabled = '<span style="color: #aaaaaa;">' . _("back") . '</span>';
        $this->left_dbl_arrow = '<strong>&laquo;</strong>';
        $this->left_dbl_arrow_disabled = '<span style="color: #aaaaaa;"><strong>&laquo;</strong></span>';
        $this->right_arrow = _("next");
        $this->right_arrow_disabled = '<span style="color: #aaaaaa;">' . _("next") . '</span>';
        $this->right_dbl_arrow = '<strong>&raquo;</strong>';
        $this->right_dbl_arrow_disabled = '<span style="color: #aaaaaa;"><strong>&raquo;</strong></span>';
        
        // Default url base. This will be set manually after instantiation 
        // in special cases like using a /my/page/# scheme.
        $this->url_base = $_SERVER['PHP_SELF'] . '?page_number=';
    }
    
    /**
     * Set the number of items per page.
     */
    function setPerPage($per_page, $default=25, $save_value=true)
    {
        // (1) By provided argument, if valid.
        // (2) By saved preference, if available.
        // (3) Set to default value if provided and valid.
        // (4) Keep as Class default of 25.
        if (is_numeric($per_page) && $per_page > 0) {
            $this->_per_page = $per_page;
            if ($save_value) {
                Prefs::setValue('items_per_page', $this->_per_page, $_SERVER['PHP_SELF']);
            }
        } else if ($save_value && Prefs::exists('items_per_page', $_SERVER['PHP_SELF'])) {
            $this->_per_page = (int)Prefs::getValue('items_per_page', $_SERVER['PHP_SELF']);
        } else if (is_numeric($default) && $default > 0) {
            $this->_per_page = $default;
        }
        $this->set_per_page_initialized = true;
    }
    
    /**
     * Set the current page number.
     */
    function setPageNumber($page_number, $save_value=true)
    {
        // (1) By provided argument, if valid.
        // (2) By saved preference, if available.
        // (3) Don't change from what was provided at class instantiation.
        if (is_numeric($page_number)) {
            if ($page_number < 1) {
                // FIXME: How to go back around to the last page? Hmmm. Set to 1 for now.
                $this->current_page = 1;
            } else {
                $this->current_page = $page_number;
            }
            if ($save_value) {
                Prefs::setValue('page_number', $this->current_page, $_SERVER['PHP_SELF']);
            }
        } else if ($save_value && Prefs::exists('page_number', $_SERVER['PHP_SELF'])) {
            $this->current_page = (int)Prefs::getValue('page_number', $_SERVER['PHP_SELF']);
        }
        $this->set_page_number_initialized = true;
    }
    
    /**
     * Set the total number of items.
     */
    function setTotalItems($total_items)
    {
        if (is_numeric($total_items) && $total_items > 0) {
            $this->total_items = $total_items;        
        } else {
            $this->total_items = 0;        
        }
        $this->set_total_items_initialized = true;
    }
    
    /**
     * After $total_items or other options are set, this function calculates
     * all the other numbers needed. If you set any variables manually, 
     * for example if $page_number comes from
     * some place other than the GET or POST array, you should call this
     * function manually, otherwise it happens at object instantiation.
     *
     * @access public
     */
    function calculate()
    {
        if (!$this->set_per_page_initialized) {
            App::logMsg(sprintf('set_per_page not initialized'), LOG_DEBUG, __FILE__, __LINE__);
        }
        if (!$this->set_page_number_initialized) {
            App::logMsg(sprintf('set_page_number not initialized'), LOG_DEBUG, __FILE__, __LINE__);
        }
        if (!$this->set_total_items_initialized) {
            App::logMsg(sprintf('set_total_items not initialized'), LOG_DEBUG, __FILE__, __LINE__);
        }
    
        // If the specified page exceedes total pages or is less than 1, set the page to 1.
        if ($this->_per_page * $this->current_page >= $this->total_items + $this->_per_page || $this->_per_page * $this->current_page < 1) {
            $this->current_page = 1;
        }
        
        // The first item to be shown on this page.
        $this->first_item = ($this->current_page - 1) * $this->_per_page;
        
        // The last item to be shown on this page.
        if ($this->total_items < $this->current_page * $this->_per_page) {
            $this->last_item = $this->total_items - 1;
        } else {
            $this->last_item = $this->current_page * $this->_per_page - 1;
        }
        
        // Zeroing. Just in case. Paranoia. Yeah, negative numbers perturb me.
        if ($this->first_item < 1) {
            $this->first_item = 0;
        }
        if ($this->last_item < 1) {
            $this->last_item = 0;
        }
        if ($this->total_items < 1) {
            $this->total_items = 0;
        }
                
        // The total number of pages.
        $this->total_pages = ceil($this->total_items / $this->_per_page);
        
        // Figure out how many page number links to print.
        if ($this->total_pages >= $this->max_num_links) {
            $this->_num_links = $this->max_num_links;
        } else {
            $this->_num_links = $this->total_pages;
        }
    }
    
    /**
     * Returns the SQL code to limit query to items that are on current page.
     */
    function getLimitSQL()
    {
        if (is_numeric($this->first_item) && is_numeric($this->_per_page)) {
            return ' LIMIT ' . addslashes($this->first_item) . ', ' . addslashes($this->_per_page) . ' ';
        } else {
            App::logMsg(sprintf('Could not find SQL to LIMIT by %s %s.', $this->first_item, $this->_per_page), LOG_WARNING, __FILE__, __LINE__);
            return '';
        }
    } 

    /**
     * Prints links to change the number of items shown per page.
     *
     * @access public
     */
    function printPerPageLinks($query_key='per_page')
    {
        $sp = '';
        for ($i=0; $i<sizeof($this->per_page_options); $i++) {
            if ($this->_per_page != $this->per_page_options[$i]) {
                printf('%s<a href="%s">%s</a>',
                    $sp,
                    App::oHREF($_SERVER['PHP_SELF'] . '?' . $query_key . '=' . $this->per_page_options[$i]),
                    $this->per_page_options[$i]
                );
            } else {
                echo $sp . '<strong>' . $this->per_page_options[$i] . '</strong>';
            }
            $sp = '&nbsp;';
        }
    }

    /**
     * Outputs an App::oHREF compatible url that goes to the page $page_number.
     * Depends on $this->base_url to build the url onto. This is used in the 
     * page_number.ihtml template.
     *
     * @param  int   $page_number    The page number this page will go to.
     *
     * @return string                The URL.
     *
     * @access public
     */
    function getPageNumURL($page_number, $carry_args=null)
    {
        return App::oHREF($this->url_base . $page_number, $carry_args);
    }
    function printPageNumURL($page_number, $carry_args=null)
    {
        echo $this->getPageNumURL($page_number, $carry_args);
    }

    /**
     * Returns an array of page number links.
     *
     * @access public
     */
    function getPageNumbersArray($carry_args=null)
    {
        $page_numbers = array();
        
        for ($i = 1; $i < $this->total_pages; $i++) {
            $page_numbers[] = array(
                'number' => $i,
                'url' => $this->getPageNumURL($i, $carry_args),
                'current' => ($this->current_page == $i)
            );
        }
        
        return $page_numbers;
    }

    /**
     * Returns a string containing the page number links.
     *
     * @access public
     */
    function getPageNumbers($carry_args=null)
    {
        $page_numbers_string = '';
        
        if ($this->current_page > $this->total_pages - floor($this->_num_links / 2)) {
            $high_num = $this->total_pages;
            $low_num = $high_num - $this->_num_links + 1;
        } else {
            $low_num = $this->current_page - floor($this->_num_links / 2);
            if ($low_num < 1) {
                $low_num = 1;
            }
            $high_num = $low_num + $this->_num_links - 1;
        }
        
        if ($this->current_page != 1) {
            // Print "first" and "previous" page links.
            if ($this->left_dbl_arrow) {
                $page_numbers_string .= sprintf('<a href="%s" title="%s">%s</a>&nbsp;', $this->getPageNumURL(1, $carry_args), _("Go to the first page"), $this->left_dbl_arrow);
            }
            if ($this->left_arrow) {
                $page_numbers_string .= sprintf('<a href="%s" title="%s">%s</a>&nbsp;&nbsp;', $this->getPageNumURL($this->current_page - 1, $carry_args), _("Go back one page"), $this->left_arrow);
            }
            // Print links to specific page numbers before the current page.
            for ($i = $low_num; $i < $this->current_page; $i++) {
                $page_numbers_string .= sprintf('<a href="%s">%s</a>&nbsp;', $this->getPageNumURL($i, $carry_args), $i);
            }
        } else {
            if ($this->left_dbl_arrow) {
                $page_numbers_string .= $this->left_dbl_arrow_disabled . '&nbsp;';
            }
            if ($this->left_arrow) {
                $page_numbers_string .= $this->left_arrow_disabled . '&nbsp;';
            }
        }
        
        if ($this->_num_links > 0) {
            // Print the current page number.
            $page_numbers_string .= sprintf('<strong>%s</strong>&nbsp;', $this->current_page);
        }
        
        if ($this->current_page < $this->total_pages) {
            // Print links to specific page numbers after the current page.
            for ($i = $this->current_page + 1; $i <= $high_num; $i++) {
                $page_numbers_string .= sprintf('<a href="%s">%s</a>&nbsp;', $this->getPageNumURL($i, $carry_args), $i);
            }
            // Print "last" and "next" page links.
            if ($this->right_arrow) {
                $page_numbers_string .= sprintf('<a href="%s" title="%s">%s</a>&nbsp;&nbsp;', $this->getPageNumURL($this->current_page + 1, $carry_args), _("Go forward one page"), $this->right_arrow);
            }
            if ($this->right_dbl_arrow) {
                $page_numbers_string .= sprintf('<a href="%s" title="%s">%s</a>&nbsp;&nbsp;', $this->getPageNumURL($this->total_pages, $carry_args), _("Go to the last page"), $this->right_dbl_arrow);
            }
        } else {
            if ($this->right_arrow_disabled) {
                $page_numbers_string .= $this->right_arrow_disabled . '&nbsp;';
            }
            if ($this->right_dbl_arrow_disabled) {
                $page_numbers_string .= $this->right_dbl_arrow_disabled;
            }
        }
        
        return $page_numbers_string;
    }
    
    function printPageNumbers($carry_args=null)
    {
        echo $this->getPageNumbers($carry_args);
    }
    
}

?>