Summary: display a pagelist in smaller slices and display navigation links
Version: 2023-03-14
Prerequisites: PmWiki 2.2.56 (compatible with PHP 5.5)
Status: stable
Maintainer: HansB
Discussion: BreakPageList-Talk

Questions answered by this recipe

How to break a pagelist display into smaller slices and provide dynamic navigation links to these.


Use BreakPageList to break a long pagelist display into several slices, and display links to each subpage as a series of page numbers. This new version adds huge flexibility for formatting the output of navigation links via entries in the pagelist template. In conjunction with the new FPLTemplate function it is also far more efficient, as it avoids double calls to pagelist.

Examples (for illustration) of navigation links displayed:

654 Results – Page 7 of 33 – Go to page Previous 1 ... 4 5 6 7 8 9 10 ... 33 Next
121 - 140 of 654 Results – Go to page Previous 2 3 4 5 6 7 8 9 10 11 12 Next


Download breakpagelist.phpΔ, copy to cookbook folder and install in config.php with


Download and install fpltemplate.phpΔ (see FPLTemplate)

If FPLTemplate gets incorporated in some form into the PmWiki core pagelist script, I will adjust the breakpagelist.php script as necessary in a future update.
Now done. Latest version needs Pmwiki 2.2.5 or later.

1. Initialise

Initialisation adds the FPLBreakPageList() function to the $FPLTemplateFunctions array. This hooks BPL into the pagelist creation process.
You can either

  • initialise BPL for the whole wiki by adding the following to config.php:
$FPLTemplateFunctions['FPLBreakPageList'] = 350; //before FPLTemplateSliceList()
  • or inititialise for a page (or group by adding to GroupHeader or GroupFooter):
Add markup (:bplinit:) to page. This will not show up at all, it just calls a special initialisation function.

2. Activate pagelist

  • Add 'start=BPL'to pagelist markup: (:pagelist ... start=BPL :)
  • Add optional parameters:
    Set breakpage chunk size with 'count=nn': (:pagelist ... start=BPL count=30 :)
    Customise default options in pagelist markup as parameters with key preceded by BPL, like
    (:pagelist ..... BPLprev=Zurück BPLnext=Weiter BPLbyitem=1 BPLnavtype=5 :) (see section #5 below for list of available optional parameters)

3. Modify the pagelist template

To show BPL page navigation links you need to edit (or create) the pagelist template referred to in the pagelist markup with parameter fmt= or template= . Your template should have a section (:template each:) which templates each result item, i.e.formats your pagelist. You will want to add page navigation at the top and/or bottom of the list, and for that you use sections starting with (:template first:) for the top and (:template last:) for the bottom. The following shows two examples, the first pretty minimal, the second more elaborate. Both are just fragments of the actual template, showing the insertion of nav links and info! You can further enhance these with wiki styles.

1. show info and nav links above pagelist on the right:

(:template first:)

2. show selective info and nav links below pagelist centered:

(:template last:)
%center% {$$BPLresults} {$$BPLfrom} - {$$BPLto} {$$BPLof} {$$BPLmax}\\
(:if !equal {$$BPLlast} 1:){$$BPLprevlink} {$$BPLnumlinks} {$$BPLnextlink}(:if:)

List of pagelist template variables:

  • {$$BPLnav} combines info and navigation links. Use this or a combination of the following:
  • {$$BPLnav} shows all navigation links including info.
  • {$$BPLprevlink} "Previous" link
  • {$$BPLnextlink} "Next" link
  • {$$BPLnumlinks} page number links;
  • {$$BPLfrom} number of first item in pagelist chunk
  • {$$BPLto} number of last item in pagelist chunk
    both together {$$BPLfrom} - {$$BPLto} gives the range of results displayed.
  • {$$BPLmax} total number of results, same as {$$PageListCount}
  • {$$BPLprev} number of previous page chunk, i.e. NOT the term 'next', which is part of the link
  • {$$BPLnext} number of next page chunk, i.e. NOT the term 'prev', which is part of the link
  • {$$BPLlast} number of last page chunk. Useful to suppress nav links if there is only one page.
  • Various text terms: {$$BPLresults}, {$$BPLpage}, {$$BPLof}, {$$BPLgoto}

4. Set BPL navigation type:

  • The number of page(slice) links and the display of a first and last link and dots is controlled by parameter navtype.
  • You can choose one number from 0,1,2,3,4,5 or 10 as navtype=n, default is navtype=3

The following tries to illustrate this with an example of current page #15 and last page #33

  • navtype=0 - Previous 15 Next
  • navtype=1 - Previous 1 ... 14 15 16 ... 33 Next
  • navtype=2 - Previous 1 ... 13 14 15 16 17 ... 33 Next
  • navtype=3 - Previous 1 ... 12 13 14 15 16 17 18 ... 33 Next
  • navtype=4 - Previous 1 ... 11 12 13 14 15 16 17 18 19 ... 33 Next
  • navtype=5 - Previous 10 11 12 13 14 15 16 17 18 19 20 Next
  • navtype=10 - Previous 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 Next

Of course if there are not so many page slices you will perhaps not see any dots or less links.
Note that the navtype determines the number links and dots displayed using variables {$$BPLnumlinks} or {$$BPLnav}, Previous and Next links can be configured separately with the prev= and next= parameters, and individually styled in the template by adding wiki styles to {$$BPLprevlink} and {$$BPLnextlink}.

5. Configuration parameters

BreakPageList comes with defaults set ready for use (in English), but allows setting custom configuration parameters in different ways:

  1. in config.php (or other local customisation file) by setting $BPLConfig['varname'] = 'value';. This will take effect to any BPL on the wiki.
  2. in (:bplinit:), like (:bplinit varname=value .... :); this will set the parameter for any BPL pagelist on the page (or group if (:bplinit:) is put into a GroupHeader or GroupFooter page).
  3. in the BPL pagelist markup, like (:pagelist ..... start=BPL count=25 BPLvarname=value ... :); this will affect that pagelist only. Note that the parameter used in the pagelist markup has an added prefix 'BPL', to avoid name conflicts.

You can set several customised parameters of course. Same parameters set later in the sequence outlined above will take precedence.

The defaults of the $BPLConfig array:

the number of results to be displayed per page. This is normally set with the count= parameter in pagelist, for instance (:pagelist ... count=10 :) will display 10 results per page.
shows page numbers for url argument (in browser's address bar). Set byitem=1 to show pagelist item numbers in url argument as item numbers.
this sets the key used for the url parameter, like for instance http://.....?n=Group.Name&p=12 for page(slice) 12
navtype= 3
this sets the navigation link type. See secton #4 above for options.

Various text string settings:
goto='Go to page'

6. Tips:

  • Use images as 'Next' and 'Previous' links by setting for instance in config
$BPLConfig['next'] = 'Attach:Site/rightarrow.gif';
$BPLConfig['prev'] = 'Attach:Site/leftarrow.gif';

or in (:bplinit:) as next=Attach:rightarrow.gif prev=Attach:leftarrow.gif


Release Notes

  • 2023-03-14: Fixed for PHP 8.1 compatibility, thanks Johnny!
  • 2017-06-20: updated markup definition for PHP 7.2 compatibility.
  • 2014-02-21: updated markup definition for PHP 5.5 compatibility.
  • 2009-08-26: new version which does not use FPLTemplate recipe, but uses new FPLTemplate function introduced in PmWiki 2.2.5 (PmWiki 2.2.5 or later is needed!)
  • 2009-02-18: initial release


See discussion at BreakPageList-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.