From phpDrone

HTML widgets are made to automatize common HTML tasks. The Form can be considered a HTML widget, but because of it's complexity, it was separated in it's own class.

PageNum

PageNum is a widget that is used in paginated lists of items. It fully automatize the generating HTML code for the pageNum and handling of page and 'how many on page' preference changing. The only thing that the programmer has to do, is retrieve the page and items per page that user choose and use it in the list's SQL query. PageNum will take care that the page is in valid range. First you have to do, is make an instance of the widget.

A good example of how a widget should be used is:

$pageNum = new PageNum($itemCount=35, $itemLabel="users", $prefName="usersperpage",
                       $prefOptionList=range(5,25,5), $maxLinks=8);
$page = $pageNum->getCurrentPage();
$itemsOnPage = $pageNum->getItemsPerPage();
print $pageNum->getHTML();

This will output a pagenum structured in thee rows: on the first row a list of pages (like on the bottom of the page of a Google result page), on the second row the list of preferences for items per page and on the third row a quick jump select in case there are a lot of pages. For more details on the meaning of the arguments and methods listed above, and a list of all PageNum methods, see the PageNum methods section bellow.

PageNum methods

The PageNum methods are here to prevent the user for passing values others than those possible with the widget and to control the way PageNum looks.

constructor

The arguments that we can pass to the constructor of the PageNum widget are:

itemCount

How many articles there are in the list. In the example above we used a fixed value for the purpose of example, but in a real case scenario, this argument will receive a dynamic value, very probably a value got with a SQL query.

itemLabel

The name of the items in the list on which this widget is used. This will be used to construct the labels used in displaying the different PageNum components

prefName

This is used internally for storing the preference that user choose for items per page. This should be different for two different PageNums in the web application if you don't want to have the same number of items per page for those two PageNums.

prefOptionList

An array listing all the preference that a user can choose. In this example, its a list between 5 and 25 with a step of 5

maxLinks (optional)

It will tell PageNum how many links, beside the current selected page, should be displayed in the widget. If this is not set (not recommended for huge lists) it will show all the pages available

getCurrentPage()

This methods return the page user selected, ensuring that the page is received is a valid one. If you don't care about this, you may also get it via the global $_GET variable from php. This functions does not receive any arguments.

getItemsPerPage()

The method will return the option that the user chooses from the preference list, ensuring that the options is received is a valid one.

hidePages()

Hides the pages row in the widget. Receives an optional boolean argument which if is evaluated as false will show the row (reverse the behavior).

hidePrefs()

Hides the preferences row in the widget. Receives an optional boolean argument which if is evaluated as false will show the row (reverse the behavior).

hideQuickJump()

Hides the quick jump row in the widget. Receives an optional boolean argument which if is evaluated as false will show the row (reverse the behavior).

getHTML()

Returns the HTML code for the PageNum widget instance.