AUTHOR:

    Marko Martinović (marko at techytalk.info) based on work from 
    Monte Ohrt's SmartyPaginate.
	Home URL: http://www.techytalk.info/savantpaginate

SYNOPSIS:

    index.php
    ---------

	/* Include classes */
	require_once('/savantpaginate_demo/savant/Savant3.php');
	require_once('/savantpaginate_demo/savant/SavantPaginate.php');

	/* SavantPaginate needs session */
	if (!isset($_SESSION)) session_start();

	/* Connect to MySQL database. Database settings like
	 * dbname, username, password and host are parsed from settings.ini */
	$dbCon = mysql_connect('dbHost', 'dbUser', 'dbPass') OR die (mysql_error());
	mysql_query('SET NAMES=\'utf8\'');

	/* Select database */
	mysql_select_db ('dbName', $dbCon) 
		or die (mysql_error());

	/* Creating new Savant object to use Savant templating engine
	 * with path to template directory. */
	$tpl = new Savant3(array('template_path' => './templates'));

	/* SAVANT PAGINATE STEP ONE: Initiate SavantPaginate. */
	SavantPaginate::connect();

	/* SAVANT PAGINATE STEP TWO (Optional): Set results limit to 20, 
	 * if omitted default is 10. */
	SavantPaginate::setLimit(20);

	/* SAVANT PAGINATE STEP THREE (Optional): Set the default number
	 * of page groupings displayed in the middle of pagination */
	SavantPaginate::setPageLimit(10);

	/* SQL query string */
	$sqlWhole = 'SELECT DistroName FROM LinuxDistributions';

	/* We execute query */
	$resultsWhole=mysql_query($sqlWhole);

	/* SavantPaginate needs to know total number of results to be able to
	 * provide pagination. */
	$numResults=mysql_numrows($resultsWhole);

	/* SAVANT PAGINATE STEP FOUR: Set total number of pagination results
	 * as received from database. */
	SavantPaginate::setTotal($numResults);

	$sqlLimited = $sqlWhole.' LIMIT '.SavantPaginate::getCurrentIndex().',
		'.SavantPaginate::getLimit();
	$resultsLimited=mysql_query($sqlLimited);
	while($row = mysql_fetch_array($resultsLimited, MYSQL_ASSOC)){
		$distroList[] = $row['DistroName'];
	}

	/* SAVANT PAGINATE STEP FIVE: Assign variables like first page, 
	 * last page, curent URI, total count
	 * and other variables needed for pagination.
	 */
	SavantPaginate::assign($tpl);

	/* Assigns variable received from database. */
	$tpl->distroList = $distroList;
	$tpl->display('index.tpl.php');


    index.tpl
    ---------

    Items <?php echo $this->paginate['first'] ?>-<?php echo $this->paginate['last'] ?> out of <?php echo $this->paginate['total'] ?> displayed.
	
	<?php echo $this->paginatefirst(); ?>
	<?php echo $this->paginateprev(); ?>
	<?php echo $this->paginatemiddle(); ?>
	<?php echo $this->paginatenext(); ?>
	<?php echo $this->paginatelast(); ?>


    style.css
    ---------

    div.savant_pagination {
        margin: 0;
        padding: 0;
    }

    div.savant_pagination a {
        border: 1px solid #AAAADD;
        color: #0D4573;
        margin: 2px;
        padding: 2px 5px;
        text-decoration: none;
    }

    div.savant_pagination a:hover, div.digg a:active {
        border: 1px solid #0D4573;
        color: #000000;
    }

    div.savant_pagination span.current {
        background-color: #0D4573;
        border: 1px solid #0D4573;
        color: #FFFFFF;
        font-weight: bold;
        margin: 2px;
        padding: 2px 5px;
    }

    div.savant_pagination span.disabled {
        border: 1px solid #EEEEEE;
        color: #DDDDDD;
        margin: 2px;
        padding: 2px 5px;
    }
    

DESCRIPTION:

    What is SavantPaginate?

    SavantPaginate is a data pagination class with plugins for the Savant template
    engine.Often times when you display a large result set on a web page (such as a
    database query), you will want to break it up across multiple pages with
    "previous" and "next" links that aid in navigating through the data.
    SavantPaginate automates the task of keeping track of the pagination and
    displaying pagination navigation links.




INSTALLATION:

    It is assumed that you are familiar with the Savant templating
    installation and setup, so I will not explain Savant template
    directories and such. Please refer to the Savant documentation for
    that information.
    
    To install SavantPaginate:

    * Copy the 'SavantPaginate.php' file to a place within your
      php_include path (or use absolute pathnames when including.)
    * Copy all of the plugins to your savant plugin directory. (located
      in the Savant3/resources directory of the savant directory.)
    

STATIC PHP METHODS:

    function connect(id = 'default', $formvar = null)
    -------------------------------------------------
    
    examples:
    SavantPaginate::connect();
    SavantPaginate::connect('mydata', $myformvars);

    connect() is required on every invocation of SavantPaginate. You can
    optionally pass an id in case you want to keep track of more than one
    pagination instance. You can also pass in your form variables as the second
    parameter in case they are not contained in the $_GET superglobal
    (default). 

    function disconnect()
    ---------------------
    
    examples:
    SavantPaginate::disconnect();
    SavantPaginate::disconnect(id = 'mydata');
    
    This clears the SavantPaginate session data. Call this when you are
    finished with pagination and want to clear all session data. If the id
    parameter is it not supplied, all pagination data is cleared.


    function reset($id = 'default')
    -------------------------------
    
    examples:
    SavantPaginate::reset();
    SavantPaginate::reset($id = 'mydata');
    
    This resets the SavantPaginate session data. Call this when you want to
    reset all pagination data to defaults.


    function setLimit($limit, $id = 'default')
    ------------------------------------------
        
    examples:
    SavantPaginate::setLimit(20);
    SavantPaginate::setLimit(20, 'mydata');
    
    setLimit() sets the number of items displayed per page, the default is 10.
    You can optionally pass an id as the second parameter.

    function getLimit($id = 'default')
    ----------------------------------
    
    examples:
    $limit = SavantPaginate::getLimit();
    
    Gets the current number of items displayed per page.


    function setTotal($total, $id = 'default')
    ------------------------------------------
        
    examples:
    SavantPaginate::setTotal(150);
    SavantPaginate::setTotal(150, 'mydata');
    
    setTotal() sets the total number if items being paginated. This could come
    from SQL_CALC_ROWS when doing a mysql query, for example. This MUST be set
    for the paginator to work! You can optionally pass an id as the second
    parameter.

    function getTotal($id = 'default')
    ----------------------------------
    
    examples:
    $total = SavantPaginate::getTotal();
    
    Gets the total number of items being paginated. You can optionally pass an
    id as the second parameter.


    function setUrl($url, $id = 'default')
    --------------------------------------
        
    examples:
    SavantPaginate::setUrl('results.php');
    SavantPaginate::setUrl('results.php', 'mydata');
    
    setUrl() sets the URL used in the paginator links to navigate from page to
    page. By default $_SERVER['PHP_SELF'] is used (current script.) You can
    optionally pass an id as the second parameter.
    
    function getUrl($id = 'default')
    --------------------------------
    
    examples:
    $url = SavantPaginate::getUrl();
    
    Gets the URL used by the paginator. You can optionally pass an id as the
    second parameter.

    function setUrlVar($urlvar, $id = 'default')
    --------------------------------------------
        
    examples:
    SavantPaginate::setUrlVar('page_next');
    SavantPaginate::setUrlVar('page_next', 'mydata');
    
    setUrlVar() sets the URL variable used by the paginator links determine the
    next page. 'next' is the default value, only change this if it conflicts
    with application variables. You can optionally pass an id as the second
    parameter.

    
    function getUrlVar($id = 'default')
    -----------------------------------
    
    examples:
    $urlvar = SavantPaginate::getUrlVar();
    
    Gets the URL variable used by the paginator. You can optionally pass an id
    as the second parameter.


    function setCurrentItem($item, $id = 'default')
    -----------------------------------------------
        
    examples:
    SavantPaginate::setCurrentItem(11);
    SavantPaginate::setCurrentItem(11, 'mydata');
    
    setCurrentItem() sets the current item being paginated to. This is normally
    set by clicking the pagination links, use this if you have a reason to jump
    to another item manually. You can optionally pass an id as the second
    parameter.


    function getCurrentItem($id = 'default')
    ----------------------------------------
    
    examples:
    $item = SavantPaginate::getCurrentItem();
    
    Gets the current item being paginated to. You can optionally pass an id as
    the second parameter. This is the same as getCurrentIndex() + 1.


    function getCurrentIndex($id = 'default')
    -----------------------------------------
    
    examples:
    $item = SavantPaginate::getCurrentIndex();
    
    Gets the index of the current item. You can optionally pass an id as
    the second parameter. This is the same as getCurrentItem() - 1. Use this
    as "X" in a MySQL query with LIMIT X,Y.


    function getLastItem($id = 'default')
    -------------------------------------
        
    examples:
    SavantPaginate::getLastItem();
    SavantPaginate::getLastItem('mydata');
    
    getLastItem() gets the last item of the currently displayed list.


    function setPrevText($text, $id = 'default')
    --------------------------------------------
        
    examples:
    SavantPaginate::setPrevText('PREVIOUS');
    SavantPaginate::setPrevText('PREVIOUS', 'mydata');
    
    Set the default text used in the "previous" pagination link. The default
    value is 'prev'.


    function getPrevText($id = 'default')
    -------------------------------------
        
    examples:
    SavantPaginate::getPrevText();
    SavantPaginate::getPrevText('mydata');
    
    Get the default text used in the "prev" pagination link.


    function setNextText($text, $id = 'default')
    --------------------------------------------
        
    examples:
    SavantPaginate::setNextText('NEXT');
    SavantPaginate::setNextText('NEXT', 'mydata');
    
    Set the default text used in the "next" pagination link. The default
    value is 'next'.

    function getNextText($id = 'default')
    -------------------------------------
        
    examples:
    SavantPaginate::getNextText();
    SavantPaginate::getNextText('mydata');

    
    Get the default text used in the "first" pagination link.

    function setFirstText($text, $id = 'default')
    --------------------------------------------
        
    examples:
    SavantPaginate::setFirstText('FIRST');
    SavantPaginate::setFirstText('FIRST', 'mydata');
    
    Set the default text used in the "first" pagination link. The default
    value is 'first'.

    function getFirstText($id = 'default')
    -------------------------------------
        
    examples:
    SavantPaginate::getFirstText();
    SavantPaginate::getFirstText('mydata');
    
    Get the default text used in the "first" pagination link.


    function setLastText($text, $id = 'default')
    --------------------------------------------
        
    examples:
    SavantPaginate::setLastText('LAST');
    SavantPaginate::setLastText('LAST', 'mydata');
    
    Set the default text used in the "last" pagination link. The default
    value is 'last'.

    function getLastText($id = 'default')
    -------------------------------------
        
    examples:
    SavantPaginate::getLastText();
    SavantPaginate::getLastText('mydata');
    
    Get the default text used in the "last" pagination link.


    function assign(&$savant, $var = 'paginate', $id = 'default')
    -------------------------------------------------------------
        
    examples:
    SavantPaginate::assign($savant);
    SavantPaginate::assign($savant, 'page_me');
    SavantPaginate::assign($savant, 'paginate', 'mydata');
    
    Sets the $this->paginate template variable. Pass the savant object as the first
    parameter. You can optionally pass a different template variable name as
    the second parameter or an id as the third parameter.


    function setPageLimit($limit, $id = 'default')
    ----------------------------------------------
        
    examples:
    SavantPaginate::setPageLimit(5);
    SavantPaginate::setPageLimit(5, 'mydata');
    
    setPageLimit() sets the default number of page groupings displayed in the
    $this->paginate_middle function. This is the same as this in the template:
    
    $this->paginate_middle['page_limit']['5']
    

    function getPageLimit($id = 'default')
    --------------------------------------
    
    examples:
    $page_limit = SavantPaginate::getPageLimit();
    
    getPageLimit() gets the default number of page groupings displayed in the
    <?php echo $this->paginatemiddle(); ?> function.


SavantPaginate VARIABLE SYNTAX

    The pagination variable is assigned with SavantPaginate::assign(). The
    pagination variable is 'paginate' by default, unless otherwise noted when
    calling SavantPaginate::assign(). Available values:
    
    $this->paginate['first'] -- the first item displayed
    $this->paginate['last'] -- the last item displayed
    $this->paginate['total'] -- the total number of items
    $this->paginate['size'] -- the size of the currently displayed segment
    $this->paginate['page_current'] -- the current page being displayed
    $this->paginate['page_total'] -- the total number of pages

    The following are used if you want to make a custom navigation bar (instead
    of using the template functions paginate_prev/middle/next)
    
    $this->paginate['url'] -- The pagination URL
    $this->paginate['urlvar'] -- The pagination URL variable (default 'next')
    $this->paginate['current_item'] -- the current item index
    $this->paginate['prev_text'] -- the text for the prev link
    $this->paginate['next_text'] -- the text for the next link
    $this->paginate['limit'] -- the page limit
    $this->paginate['page[N]']['number'] -- the page number
    $this->paginate['page[N]']['item_start'] -- the starting item for this page
    $this->paginate['page[N]']['item_end'] -- the ending item for this page
    $this->paginate['page[N]']['is_current'] -- boolean true on the current page
    
    Examples:
    
    if($this->paginate['size'] > 1){
      Items $this->paginate['first']-$this->paginate['last'] of $this->paginate['total'] displayed.
	}
    else{
      Item $this->paginate['first'] of $this->paginate['total'] displayed.    
    }
    
    
SavantPaginate FUNCTION SYNTAX:    
    
    There are several different template functions available. They are as follows:
    
    $this->paginate_first
    $this->paginate_first['id']['mydata']
    $this->paginate_first['text']['FIRST"}
    $this->paginate_prev
    $this->paginate_prev['id']['mydata'}
    $this->paginate_prev['text']['&lt;&lt;']
    $this->paginate_next
    $this->paginate_next['id']['mydata"]
    $this->paginate_next['text']['&lt;&lt;']
    $this->paginate_last
    $this->paginate_last['id']['mydata']
    $this->paginate_last['text']['FIRST']
     
    The functions above are used to display links that take you to the first,
    previous, next and last pagination groupings. Use the "id" parameter only if
    you are not using the default id. The "text" parameter changes the default
    text of the link. Any unknown attributes will be passed through to the
    links as HTML attributes.
    
    $this->paginate_middle
    $this->paginate_middle ['id']['mydata']
    $this->paginate_middle ['format']['range']
    $this->paginate_middle ['page_limit']['5']

    $this->paginate_middle displays the links to all of the pagination groupings. The
    format attribute 'range' displays the item range instead of the page numbers. 
    ([1-5][6-10][11-15] instead of [1][2][3]). The default is 'page'. The page_limit 
    attribute sets the maximum number of page groupings to display
    (if you have too many pages, limit the display with this).

CREDITS:

    Thanks to the Monte Ohrt, author of SmartyPaginate for making creation of SavantPaginate
    possible.
