Плагин Pagelist

Плагин Pagelist построен вокруг функции sedby_pagelist и предназначен для формирования и вывода кастомизируемых списков страниц со следующими возможностями:

1. Настраиваемый шаблон для любого вызова
2. Настраиваемые количество, сортировка и условия генерации списка страниц
3. Опциональная паджинация
4. Опциональное кэширование вывода

Плагин требует наличия предустановленной библиотеки Cotlib.

Функция sedby_pagelist() имеет следующие аргументы:

sedby_pagelist
(
   $tpl = 'pagelist', // 01. имя шаблона (по умолчанию pagelist)
   $items = 0,        // 02. количество записей (0 – вывести все)
   $order = '',       // 03. сортировка в формате MySQL
   $extra = '',       // 04. дополнительные MySQL-запросы
   $mode = '',        // 05. режим (single, black, white, array_black, array_white)
   $cats = '',        // 06. разделы согласно указанному режиму
   $subs = 0,         // 07. включить страницы во всех подразделах
   $noself = 0,       // 08. исключить страницу, с которой вызывается функция
   $offset = 0,       // 09. сдвиг на указанное количество записей
   $pagination = '',  // 10. код паджинации для URL'ов
   $ajax_block = '',  // 11. ID блока для AJAX-паджинации
   $cache_name = '',  // 12. имя записи в таблице кэша
   $cache_ttl = ''    // 13. срок жизни кэша в секундах
)

Примеры использования аргументов

Самые простые варианты включают в себя только первые три или четыре аргумента:

// Вывести все страницы сайта
{PHP|sedby_pagelist('pagelist')}

// Вывести 5 последних страниц сайта
{PHP|sedby_pagelist('pagelist', 5, 'page_date DESC')}

// Вывести 5 последних страниц из раздела с кодом news
{PHP|sedby_pagelist('pagelist', 5, 'page_date DESC', 'page_cat = "news"')}

Обратите внимание на то, что в самом простом случае выбора раздела (один раздел, без страниц из вложенных подразделов) удобнее и быстрее в аргументе $extra просто указать MySQL условие вроде:

page_cat = "news"

В таком случае не будет задействована функция умной выборки требуемых разделов со страницами, а вызов будет и выглядеть проще и (технически) выполняться быстрее.

Более сложные варианты:

// Вывести топ-10 страниц по посещаемости
{PHP|sedby_pagelist('pagelist', 10, 'page_count DESC')}

// Вывести страницы из предварительно сформированной строки с кодами разделов
// с сортировкой по дате, включая страницы из подразделов
{PHP.some_string|sedby_pagelist('pagelist', 0, 'page_count DESC', '', 'white', $this, 1)}

// Вывести страницы из предварительно сформированного массива с кодами разделов
// с сортировкой по дате, включая страницы из подразделов
{PHP.some_array|sedby_pagelist('pagelist', 0, 'page_count DESC', '', 'array_white', $this, 1)}

С массивом все понятно, а если для белого или черного списка вы используете строку, коды разделов необходимо указать через точку с запятой:

{PHP|sedby_pagelist('pagelist', 0, 'page_count DESC', '', 'white', 'news; articles', 1)}

Если вы хотите вывести только те страницы, которые были опубликованы за определенный срок, необходимы два этапа. На первом считаем точку отсчета в секундах. Это проще сделать, например, в php-файле темы:

$R['admin_home_recent'] = 14; // Это дни
$R['admin_home_recent_stamp'] = $sys['now'] - $R['admin-home-recent'] * 86400; // А это уже секунды

Теперь сформированную ресурсную строку можно отдать в аргумент $extra нашей функции в TPL-шаблоне:

{PHP.R.admin_home_recent_stamp|sedby_pagelist('pagelist', '', 'page_date DESC', 'page_date > $this')}

Последние четыре аргумента не вызовут больших сложностей в понимании:

• непустой $pagination включит паджинацию с количеством записей на страницу, равным аргументу $items
• непустой $ajax_block включит паджинацию в режиме аякса
• непустые $cache_name и $cache_ttl включат кэширование вывода

// Вывести последнее из новостей и блога с разбивкой на страницы в режиме аякса
<div id="pl_ajax">
   {PHP|sedby_pagelist('pagelist', 5, 'page_date DESC', '', 'white', 'news;blog', 0, 0, 0, 'pag', 'pl_ajax')}
</div>

// Вывести 10 последних новостей и закэшировать результат на 24 часа
{PHP|sedby_pagelist('pagelist', 10, 'page_date DESC', 'page_cat = "news"', '', '', 0, 0, 0, '', '', 'cached_news', 86400)}

Логика использования кэша и паджинации (в порядке выполнения функции)

Кэш Pagelist включается при выполнении всех следующих условий:

• в файле config.php активирована настройка $cfg['cache']
• значение $cache_name непустое
• значение $cache_ttl целое и больше нуля

Закэшированные данные считываются и сразу передаются в вывод при выполнении всех следующих условий:

• включен кэш
• в таблице кэша присутствует запись с именем, соответствующим аргументу $cache_name

Если считывания данных не произошло, функция начинает генерировать вывод.

Паджинация включается при выполнении всех следующих условий:

• не включен кэш
• значение $items целое и больше нуля
• значение $pagination непустое

Аякс будет задействован при включенной паджинации и если:

• в настройках сайта включен аякс ($cfg['turnajax']) и
• в настойках плагина включена опция "Использовать AJAX для паджинации" и
• аргумент $ajax_block непустой

Напомню, что при использовании аякса вызов функции в шаблоне должен быть "обернут" в div с атрибутом ID, равным значению $ajax_block. Примерно так:

<div id="pl_ajax">
   {PHP|sedby_pagelist('pagelist', 5, '', '', 'single', 'news', 0, 0, 0, 'pag', 'pl_ajax')}
</div>

Вывод функции кэшируется если:

• кэш включен

Главное правило: нельзя одновременно использовать кэш и паджинацию (включая AJAX). Оно исходит из того, что "это просто не будет работать". Соответственно аргументы 10 и 11 нельзя использовать одновременно с 12 и 13. Это необходимо запомнить.

Структура шаблона и правило имен

Имя шаблона плагина Pagelist должно подчиняться общему правилу имен.

Типовой шаблон плагина имеет следующую структуру:

<!-- BEGIN: MAIN -->

<ul>
<!-- BEGIN: PAGE_ROW -->
    <li class="{PAGE_ROW_ODDEVEN}">
        <a href={PAGE_ROW_URL}>{PAGE_ROW_NUM}. {PAGE_ROW_SHORTTITLE}</a>
    </li>
<!-- END: PAGE_ROW -->

<!-- BEGIN: NO_ROW -->
    <li>
        {PHP.L.Empty}
    </li>
<!-- END: NO_ROW -->
</ul>
 
<!-- IF {PAGE_TOP_PAGINATION} -->
<p>
    {PAGE_TOP_PAGEPREV}{PAGE_TOP_PAGINATION}{PAGE_TOP_PAGENEXT}
</p>
<!-- ENDIF -->

<!-- END: MAIN -->

В регулярном блоке доступны следующие TPL-теги:

• стандартные теги {PAGE_ROW_NUM} и {PAGE_ROW_ODDEVEN}
• все pagetags с префиксом PAGE_ROW_
• все usertags с префиксом PAGE_ROW_USER_
• {PAGE_ROW_COMMENTS_COUNT} (количество комментариев к странице, при включении опции "Создавать теги для плагина Comments" и активном одноименном плагине)
• {PAGE_ROW_RATINGS_DISPLAY}, {PAGE_ROW_RATINGS_AVERAGE}, {PAGE_ROW_RATINGS_COUNT} (при включении опции "Создавать теги для плагина Star Ratings" и активном одноименном плагине)
• {PAGE_ROW_THANKS_COUNT} (количество лайков при включении опции "Создавать теги для плагина Thanks" и активном одноименном плагине)

Стандартные теги паджинации:

• {PAGE_TOP_PAGINATION} – сгенеренная паджинация
• {PAGE_TOP_PAGEPREV} – ссылка на предыдущую страницу паджинации
• {PAGE_TOP_PAGENEXT} – ссылка на следующую страницу паджинации
• {PAGE_TOP_FIRST} – ссылка на первую страницу паджинации
• {PAGE_TOP_LAST} – ссылка на последнюю страницу паджинации
• {PAGE_TOP_CURRENTPAGE} – ссылка на текущую страницу паджинации
• {PAGE_TOP_TOTALLINES} – всего элементов паджинации
• {PAGE_TOP_MAXPERPAGE} – элементов на страницу паджинации
• {PAGE_TOP_TOTALPAGES} – всего страниц паджинации

Об истории создания плагина читаем здесь.

Приятного использования. Свои отзывы, пожелания и багрепорты отставляйте в комментариях на нашем сайте (не требуют регистрации) или в Issues на Github.