2.7.3. Pagesystem

Pagesystem instruction is used to integrate OPT with the pagination systems from the web application. It allows to define the layout of the page list used in the templates, so that it is independent from the PHP code. The instruction takes from one to three parameters:

Table 2.5. Pagesystem: parameters

Pagesystem: parameters
NameTypeRequired?Description
nameIDYesThe name of the pagesystem. Moreover, The pagination system is imported from the block with the specified name.
npDisplayExpressionNoAn expression that controls, whether the links to the next and previous page are shown (if provided). By default set to 1.
flDisplayExpressionNoAn expression that controls, whether the links to the first and last page are shown (if provided). By default set to 1.

The layout is defined in the special tags inside the instruction. Their names and meanings are:

  1. page - the look of a link to a page.
  2. active - the look of a link to an active page.
  3. separator - the look of a separator, which hides a bigger set of pages in order to make the list smaller.
  4. next - the look of a link to the next page.
  5. prev - the look of a link to the previous page.
  6. first - the look of a link to the first page.
  7. last - the look of a link to the last page.

The number of tags necessary to work depends on the pagination system used by the programmer, but unsually the first tree ones are the minimum. In all of them, the two variables are provided: {@url} with the URL address to the page, and {@title} with the page name. They are returned by the pagination system.

Example 2.44. The simplest pagination system port.

<p>{pagesystem=ps}
{page}[ <a href="{@url}">{@title}</a> ]{/page}
{active}&lt; <strong><a href="{@url}">{@title}</a></strong> &gt;{/active}
{separator}...{/separator}
{/pagesystem}</p>

Example 2.45. More advanced pagination system port.

<p>{pagesystem=ps}
{page}[ <a href="{@url}">{@title}</a> ]{/page}
{active}&lt; <strong><a href="{@url}">{@title}</a></strong> &gt;{/active}
{separator}...{/separator}
{prev}<a href="{@url}">prev</a> :: {/prev}
{next} :: <a href="{@url}">next</a>{/next}
{first}<a href="{@url}">first</a> :: {/first}
{last} :: <a href="{@url}">last</a>{/last}
{/pagesystem}</p>

Like in trees, the pagesystem design can be kept globally in the bindGroup instruction and linked with use tag.

Example 2.46. More advanced pagination system port.

{bindGroup=pagesystemDesign}
	{page}[ <a href="{@url}">{@title}</a> ]{/page}
	{active}&lt; <strong><a href="{@url}">{@title}</a></strong> &gt;{/active}
	{separator}...{/separator}
	{prev}<a href="{@url}">prev</a> :: {/prev}
	{next} :: <a href="{@url}">next</a>{/next}
	{first}<a href="{@url}">first</a> :: {/first}
	{last} :: <a href="{@url}">last</a>{/last}
{/bindGroup}							  
							  
<p>{pagesystem=ps}{use snippet="pagesystemDesign"/}{/pagesystem}</p>

When it comes to the programmers' point of view, a pagination system is an object of a class that implements the ioptPagesystem interface. It provides some methods to integrate the class with the pagesystem instruction. Each of them returns an assotiative array with three elements:

  1. t - element type: 0 - normal page; 1 - active page; 2 - separator;
  2. p - page name
  3. l - the link to the page.

If there are no pages to display or the specified part of the interface is not supported by the pagination system, the methods should return nothing. Below, you can see a sample implementation of the interface.

Example 2.47. Sample implementation of ioptPagesystem interface.

<?php
	class pagesystem implements ioptPagesystem
	{
		private $buffer;		// the buffer, where the page information is generated to.
		private $prev;			// the number of the previously returned page

		// some other class methods here...

		/*
	 	 * Returns the next page from the buffer or nothing, if the script reaches the end of the buffer.
		 */
		public function getPage()
		{
			if(!is_array($this -> buffer))
			{
				$this -> prepare(); // generate the list of pages, if it does not exist
			}
			$page = key($this -> buffer); // try to get the next page
			if(!is_null($page))
			{
				if($this -> prev + 1 != $page) // there is a hole in the page numbers, insert the separator here.
				{
					$this -> prev = $page - 1;
					return array('t' => 2, 'p' => 0, 'l' => '');
				}

				$this -> prev = $page;
				next($this->buffer); // jump to the next page
				return array('t' => ($page == $this->from_pos ? 1 : 0), // return the page, checking whether it's the active one
					'p' => $page,
					'l' => $this -> l($page)
				);
			}
		} // end getPage();

		/*
	 	 * Returns the information for the "next page" link.
		 */
		public function nextPage()
		{
			if($this -> from_pos < $this -> pages)
			{
				return array('t' => 0, 'p' => $this->from_pos+1, 'l' => $this->l($this->from_pos+1));
			}
		} // end nextPage();

		/*
		 * Returns the information for the "previous page" link.
		 */
		public function prevPage()
		{
			if($this -> from_pos > 1)
			{
				return array('t' => 0, 'p' => $this->from_pos-1, 'l' => $this->l($this->from_pos-1));
			}
		} // end prevPage();

		/*
		 * Returns the information for the "first page" link.
		 */
		public function firstPage()
		{
			if($this -> pages > 1)
			{
				return array('t' => 0, 'p' => 1, 'l' => $this->l(1));
			}
		} // end firstPage();

		/*
		 * Returns the information for the "last page" link.
		 */
		public function lastPage()
		{
			if($this -> pages > 1)
			{
				return array('t' => 0, 'p' => $this->pages, 'l' => $this->l($this->pages));
			}
		} // end lastPage();
	}
?>

The pagesystem object is loaded to the template with the standard optClass::assign() method.