DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:pagelist:development

Pagelist plugin

How to use Pagelist in your plugin

You use pagelist for listing a list of pages. You need an array which has rows with at least the 'id' entry set.

You can add your own column(s) as well. Because the column can be requested from any pagelist (also for most plugins using an internally pagelist) you have to implement th() and td() - only for built-in plugins? For efficiency, you can add the data for this column directly to setHeader() and addPage() as well.

addColumn() with data via addPage()/setHeader()

You can use pagelist plugin in your plugin. With addColumn() you can (optional) add your own column as well. The data for that column is here provided via addPage() and setHeader().

example/syntax/component.php
...
$flags = ['header']; //show table header
$header = [
    'yourcolumn' => 'Your Column'
];
$pages = [
    ['id' => 'firstpage', 'yourcolumn' => 'Text 1'],
    ['id' => 'secondpage', 'yourcolumn' => 'Text 2'],
];
if($pagelist = $this->loadHelper('pagelist')) {
    $pagelist->addColumn('example', 'yourcolumn');
    $pagelist->setHeader($header); //available since 2022-10-17
    $pagelist->setFlags($flags);
    $pagelist->startList('plugin_example_class');
    foreach($pages as $page) {
        $pagelist->addPage($page);
    }
    $renderer->doc .= $pagelist->finishList();
}
...

addColumn() with data via th()/td()

If data for the extra column is not provided before, the pagelist will request it from the th() and td() provided in helper.php of your plugin.

example/helper.php
<?php
class helper_plugin_example extends DokuWiki_Plugin {
    /**
     * Returns the column header text for the Pagelist Plugin
     * 
     * @param string $column column name as set in addColumn()
     * @param string $class by reference, class set to td of the table. Replaces that default the column name is set as class 
     * @return string text, escaped by Pagelist plugin
     */
    public function th($column=null, &$class = null) {
        if($column == 'yourcolumn') {
            $content = 'Your Column';
        } else {
            $content = $this->getLang('othercolumn');
        }
    }
    //eventually also possible, if you have only one column and not a css class per cell:
    public function th() {
        return $this->getLang('yourcolumn');
    }
 
    /**
     * Returns the cell data for the Pagelist Plugin
     *
     * @param string $id page id
     * @param string $column column name as set in addColumn()
     * @param string $class by reference, class set to td of the table. Replaces that default the column name is set as class 
     * @return string escaped html content for cell of table
     */
    public function td($id, $column=null, &$class = null) {
        $class .= 'special';
        if($column == 'yourcolumn') {
            $content = '...';
        } else {
            $content = '...';
        }
        return hsc($content);
    }
    //eventually also possible, if you have only one column and not a class per cell::
    public function td($id) {
        $content = '...';
        return hsc($content);
    }
}

Description of available pagelist functions

  • (optional) addColumn($plugin, $column) add $column to the table.
    Gets data via addPage()/setHeader() or uses helper from plugin name $plugin for displaying:
    • cells of the page row with td($id, $column=null, &$class = null)
    • cells of the header row with th($column=null, &$class = null).
  • (optional) modifyColumn($column, $value) overwrites $column value, set to false to disable.
  • (optional) setFlags($flags) with $flags an array with flags as strings. Call this function after addColumn().
  • (optional) setHeader($header) with $header having html entries per column, if not given default pagelist values or plugin->th() are used. You have to escape user input with hsc().
  • (required) startList($class = null) starts a list or table, if enabled it prints also the header. $class can add a table class.
  • (required), per row addPage($page) with associated array $page with per column an entry. For your own columns you must provide the html, you have to escape user input.
    • 'id' ⇒ string page id (required)
    • 'title' ⇒ string First headline, otherwise page id TODO always replaced by id or title from metadata?
    • 'titleimage' ⇒ string media id
    • 'date' ⇒ int timestamp of creation date, otherwise modification date (e.g. sometimes needed for plugin)
    • 'user' ⇒ string $meta['creator']
    • 'desc' ⇒ string $meta['description']['abstract']
    • 'description' ⇒ string description set via pagelist syntax
    • 'exists' ⇒ bool page_exists($id)
    • 'perm' ⇒ int auth_quickaclcheck($id)
    • 'draft' ⇒ string $meta['type'] set by blog plugin
    • 'priority' ⇒ string priority of task: 'low', 'medium', 'high', 'critical'
    • 'class' ⇒ string class set for each row
    • 'file' ⇒ string wikiFN($id)
    • 'section' ⇒ string id of section, added as #ancher to page url
  • (required) finishList() closes a list or table, returns the html

If you add you own column for your plugin, you must implement a helper.php with th() and td().

  • for each row, the $column is filled with td($id, $column=null, &$class = null) (escape user input with hsc())
  • in the header the $column is filled with th($column=null, &$class = null) (escaping done by pagelist).

For further documentation of the arguments see PHPDocs of the source code.

List dependencies per plugin

Some notes used for the cleanup of the Pagelist plugin (September 2022).

authorstats
uses: loadHelper
setFlags
startList
addPage
finishList
cloud
depends on tag and searchstats plugins
⇒ unclear if it depends (indirectly) on pagelist
dir
copied css styles, seems independent further
pageimage
integrated with pagelist
provides: td($id)
th()
tagsections
depends on tag (so on pagelist?)
task
provides: th()
td($id)
uses: plugin_load('helper','pagelist')
header array
column array
addCOlumn
setFlags
startList
addPage
finishList
tiledblog
depends on blog
editor
uses: plugin_isdisabled use loadHelper
plugin_load use loadHelper
column array
setFlags
startList
addPage
finishList
tag
provides: td($id)
th()
uses: loadhelper
- topic sort (overwrite defaults)
rsort (overwrite defaults)
setFlags
startList
sort
rsort
addPage
finishList
-searchtags loadHelper
setFlags
startList
addPage
finishList
-action loadHelper
setFlags
startList
addPage
finishList
tagfilter
provides: td($id,$col)
th($tag='')
uses: plugin_isdisabled use loadHelper
-syntax plugin_load use loadHelper
addColumn
setFlags
startList
addPage
finishList
-action addColumn
setFlags
startList
addPage
finishList
blog
uses: plugin_isdisabled use loadHelper
-archive plugin_load use loadHelper
setFlags
startList
addPage
finishList
-autoarchive plugin_isdisabled use loadHelper
plugin_load use loadHelper
setFlags
startList
addPage
finishList
discussion
provides: th()
-helper td($id, $num=null)
uses: plugin_isdisabled use loadHelper
-threads plugin_load use loadHelper
column array
setFlags
startList
addPage
finishList
linkback
provides: th()
td($id, $number=null)
changes
optionally: pagelist plugin used by setting a flag
uses: plugin_load
setFlags
startList
addPage
finishList
VERY OLD - 2008:
pageseditees –not supported anymore–
uses: plugin_load
page array
_meta array better use get_metadata directly
_getMeta
listeabo –not supported anymore–
uses: plugin_load
page array
_meta array better use get_metadata directly
_getMeta
snap –not supported anymore–
uses: plugin_load
-syntax.php.ori page
_meta better use get_metadata directly
_getMeta
-helper plugin_load
page
_meta better use get_metadata directly
_getMeta
favoris –not supported anymore–
uses: plugin_load
page better use get_metadata directly
_meta
_getMeta
COMMENTED OUT:
pageindex –not supported–
uses: plugin_load
startList not dependent
addPage
finishList
plugin/pagelist/development.txt · Last modified: 2022-10-17 22:58 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki