documentation/manual/en/tutorials/paginator-simple.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.paginator.simple">
   4     <title>Simple Examples</title>
   5
   6     <para>
   7         In this first example we won't do anything spectacular, but hopefully it will
   8         give you a good idea of what <classname>Zend_Paginator</classname> is designed to do.
   9         Let's say we have an array called $data with the numbers 1 to 100 in it, which
  10         we want to divide over a number of pages. We can use the static
  11         <methodname>factory()</methodname> method in the <classname>Zend_Paginator</classname>
  12         class to get a <classname>Zend_Paginator</classname> object with our array in it.
  13     </para>
  14
  15     <programlisting language="php"><![CDATA[
  16 // Create an array with numbers 1 to 100
  17 $data = range(1, 100);
  18
  19 // Get a Paginator object using Zend_Paginator's built-in factory.
  20 $paginator = Zend_Paginator::factory($data);
  21 ]]></programlisting>
  22
  23     <para>
  24         We're already almost done! The $paginator variable now contains a reference to the
  25         Paginator object. By default it is setup to display 10 items per page.
  26         To display the items for the currently active page, all you need to do is iterate
  27         over the Paginator object with a foreach loop. The currently active page defaults
  28         to the first page if it's not explicitly specified. We will see how you can select
  29         a specific page later on. The snippet below will display an unordered list containing the
  30         numbers 1 to 10, which are the numbers on the first page.
  31     </para>
  32
  33     <programlisting language="php"><![CDATA[
  34 // Create an array with numbers 1 to 100
  35 $data = range(1, 100);
  36
  37 // Get a Paginator object using Zend_Paginator's built-in factory.
  38 $paginator = Zend_Paginator::factory($data);
  39
  40 ?><ul><?php
  41
  42 // Render each item for the current page in a list-item
  43 foreach ($paginator as $item) {
  44     echo '<li>' . $item . '</li>';
  45 }
  46
  47 ?></ul>
  48 ]]></programlisting>
  49
  50     <para>
  51         Now let's try and render the items on the second page. You can use the
  52         <methodname>setCurrentPageNumber()</methodname> method to select which page you want to
  53         view.
  54     </para>
  55
  56     <programlisting language="php"><![CDATA[
  57 // Create an array with numbers 1 to 100
  58 $data = range(1, 100);
  59
  60 // Get a Paginator object using Zend_Paginator's built-in factory.
  61 $paginator = Zend_Paginator::factory($data);
  62
  63 // Select the second page
  64 $paginator->setCurrentPageNumber(2);
  65
  66 ?><ul><?php
  67
  68 // Render each item for the current page in a list-item
  69 foreach ($paginator as $item) {
  70     echo '<li>' . $item . '</li>';
  71 }
  72
  73 ?></ul>
  74 ]]></programlisting>
  75
  76     <para>
  77         As expected, this little snippet will render an unordered list with the numbers
  78         11 to 20 in it.
  79     </para>
  80
  81     <para>
  82         These simple examples demonstrate a small portion of what can be achieved with
  83         <classname>Zend_Paginator</classname>. However, a real application rarely reads its data
  84         from a plain array, so the next section is dedicated to showing you how you can use
  85         Paginator to paginate the results of a database query. Before reading on, make sure you're
  86         familiar with the way <classname>Zend_Db_Select</classname> works!
  87     </para>
  88
  89     <para>
  90         In the database examples we will look at a table with blog posts called 'posts'.
  91         The 'posts' table has four columns: id, title, body, date_created.
  92         Let's dive right in and have a look at a simple example.
  93     </para>
  94
  95     <programlisting language="php"><![CDATA[
  96 // Create a select query. $db is a Zend_Db_Adapter object, which we assume
  97 // already exists in your script.
  98 $select = $db->select()->from('posts')->order('date_created DESC');
  99
 100 // Get a Paginator object using Zend_Paginator's built-in factory.
 101 $paginator = Zend_Paginator::factory($select);
 102
 103 // Select the second page
 104 $paginator->setCurrentPageNumber(2);
 105
 106 ?><ul><?php
 107
 108 // Render each the title of each post for the current page in a list-item
 109 foreach ($paginator as $item) {
 110     echo '<li>' . $item->title . '</li>';
 111 }
 112
 113 ?></ul>
 114 ]]></programlisting>
 115
 116     <para>
 117         As you can see, this example is not that different from the previous one.
 118         The only difference is that you pass a <classname>Zend_Db_Select</classname> object to the
 119         Paginator's <methodname>factory()</methodname> method, rather than an array.
 120         For more details on how the database adapter makes sure that your query
 121         is being executed efficiently, see the <classname>Zend_Paginator</classname> chapter in the
 122         reference manual on the DbSelect and DbTableSelect adapters.
 123     </para>
 124 </sect1>