<= [[wiki:plugin:pagelist|Pagelist plugin]]

====== Как использовать список страниц в вашем плагине ======

Вы используете список страниц для вывода списка страниц. Вам нужен массив, в котором есть строки, по крайней мере, с ''%%'id'%%'' набором записей.

Вы также можете добавить свои собственные столбцы. Ниже описаны два способа.

===== addColumn() с данными через addPage()/setHeader() =====

(//Предпочтительный подход//) Вы можете использовать плагин списка страниц в своем плагине. Вы также ''addColumn()'' можете (необязательно) добавить свой собственный столбец. Данные для этого столбца предоставляются с помощью ''addPage()'' и ''setHeader()''.

<code php example/syntax/component.php>
...
$flags = ['header']; //показать заголовок таблицы 
$header = [
    'yourcolumn' => 'Your Column'
];
$pages = [
    ['id' =>  'первая страница' ,  'ваша колонка'  => 'Text 1'],
    ['id' =>  'вторая страница' ,  'ваша колонка'  => 'Text 2'],
    ['id' => '3rd', 'yourcolumn' => '<em>3&amp;4</em> with user input escaping'],
];
if($pagelist = $this->loadHelper('pagelist')) {
    $pagelist->addColumn('example', 'yourcolumn');
    $pagelist->setHeader($header); //доступно с 17 октября 2022 г. 
    $pagelist->setFlags($flags);
    $pagelist->startList('plugin_example_class');
    foreach($pages as $page) {
        $pagelist->addPage($page);
    }
    $renderer->doc .= $pagelist->finishList();
}
...
</code>

===== addColumn() с данными через th()/td() =====

(//Альтернативный подход//) Если данные для дополнительного столбца не были предоставлены ранее, список страниц запросит их у вашего плагина ''th()'' и ''td()'' предоставит его. ''helper.php'' Часто этот подход требует временного хранения данных, что снижает его производительность.

<code php example/helper.php>
<?php
class helper_plugin_example extends DokuWiki_Plugin {
    /**
     * Возвращает текст заголовка столбца для плагина списка страниц.
     *
     * @param string $column имя столбца, заданное в addColumn()
     * @param string $class по ссылке, класс установлен в td таблицы. Заменяет это значение по умолчанию, имя столбца установлено как класс.
     * Текст строки @return, экранированный плагином Pagelist
     */ 
    public function th($column=null, &$class = null) {
        if($column == 'yourcolumn') {
            $content = 'Your Column';
        } else {
            $content = $this->getLang('othercolumn');
        }
    }
    //в конечном итоге это также возможно, если у вас есть только один столбец, а не класс CSS для каждой ячейки:
    public function th() {
        return $this->getLang('yourcolumn');
    }

    /**
     * Возвращает данные ячейки для плагина списка страниц.
     *
     * @param string $id идентификатор страницы
     * @param string $column имя столбца, заданное в addColumn()
     * @param string $class по ссылке, класс установлен в td таблицы. Заменяет это значение по умолчанию, имя столбца установлено как класс.
     * @return строка экранирует HTML-содержимое ячейки таблицы
     */ 
    public function td($id, $column=null, &$class = null) {
        $class .= 'special';
        if($column == 'yourcolumn') {
            $content = '...';
        } else {
            $content = '...';
        }
        return hsc($content);
    }
     //в конечном итоге это также возможно, если у вас есть только один столбец, а не класс на ячейку:: 
    public function td($id) {
        $content = '...';
        return hsc($content);
    }
}
</code>
===== Описание доступных функций списка страниц =====

  * (необязательно) addColumn($plugin, $column)добавьте в таблицу $column.
  * Получает данные через addPage()/setHeader() или использует хелпер из имени плагина $plugin для отображения:
    * ячейки строки страницы сtd($id, $column=null, &$class = null)
    * ячейки строки заголовка с th($column=null, &$class = null).
  * (необязательно) modifyColumn($column, $value)перезаписывает значение $column, для отключения которого установлено значение false.
  * (необязательно) setFlags($flags)с $flags — массив с флагами в виде строк. Вызовите эту функцию после addColumn().
    * Рядом с флагами по умолчанию можно использовать дополнительный флаг defaultsortby=<property>для установки предпочтения сортировки без включения сортировки.
  * (необязательно) setHeader($header)с $header, содержащим записи html для каждого столбца, если не указаны значения списка страниц по умолчанию или используются плагин->th(). Вам нужно избежать пользовательского ввода с помощью hsc() .
  * (обязательно) startList($class = null)запускает список или таблицу, если включено, печатается также заголовок. $class может добавить класс таблицы.
  * (обязательно), для каждой строки addPage($page)со связанным массивом $page с записью для каждого столбца. Для ваших собственных столбцов вы должны предоставить HTML, вам нужно избежать пользовательского ввода .
    * 'id' ⇒ строковый идентификатор страницы (обязательно).
    * 'title' ⇒ строка Первый заголовок, иначе идентификатор страницы; исключение: если используется titleimage, это используется для атрибута title&alt изображения.
    * 'titleimage' ⇒ строковый идентификатор носителя
    * 'date' ⇒ int временная метка даты создания, в противном случае дата изменения (например, иногда требуется для плагина)
    * 'пользователь' ⇒ строка $meta['создатель']
    * 'desc' ⇒ строка $meta['description']['abstract']
    * 'описание' ⇒ строковое описание, заданное с помощью синтаксиса списка страниц.
    * 'symmary' ⇒ строковая сводка последнего изменения страницы $meta['last_change']['sum']
    * 'существует' ⇒ bool page_exists($id)
    * 'разрешение' ⇒ int auth_quickaclcheck($id)
    * 'черновик' ⇒ строка $meta['type'], заданная плагином блога.
    * «приоритет» ⇒ строковый приоритет задачи: «низкий», «средний», «высокий», «критический».
    * 'class' ⇒ класс строки, установленный для каждой строки.
    * 'файл' ⇒ строка wikiFN($id)
    * 'section' ⇒ строковый идентификатор раздела, добавленный как #ancher к URL-адресу страницы.
  * (обязательно) finishList()закрывает список или таблицу, возвращает html
Если вы добавляете собственный столбец для своего плагина, рекомендуется добавлять через addPage()HTML для каждой ячейки столбца. В качестве альтернативы вы должны реализовать helper.phpwith th()и td().

  * для каждой строки столбец $ заполняется td($id, $column=null, &$class = null)(экранируйте пользовательский ввод с помощью hsc())
  * в заголовке заполняется столбец $ th($column=null, &$class = null)(экранирование осуществляется с помощью списка страниц).

Дополнительную документацию по аргументам см. в PHPDocs исходного [[https://github.com/dokufreaks/plugin-pagelist/blob/master/helper.php|кода]].


===== Список зависимостей для каждого плагина =====
Некоторые примечания, использованные для очистки плагина Pagelist (сентябрь 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               |                              |                                   |
|                       | setFlags                                                |                                   |
|                       | startList                                               |                                   |
|                       | 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, $col = null, &$class = null, $num = null)   $num is used interally in discussion plugin                                  |                                   |
|                       |                                                         |                                   |
|                 uses: |                                        |                 |
| -threads              | loadHelper                                             |                      |
|                       | addColumn                                               |                                   |
|                       | 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                                              |                                   |