Компонент позволяет автоматизировать или упростить работу с пагинацией, сортировкой и фильтрацией списка элементов., (*1)
Работа начинается с инициализации объекта Navigator с передачей в него объектов Request и Manager., (*2)
$navi = new Navigator($request, $manager);, (*3)
Пагинация
Объект Navigator предоставляет набор методов, для получения первой, последней, следующей, предыдущей страниц, а также
быстрой генерации объектов URL для них., (*4)
~~~ php
$navi->getPage(); // получение номера текущей страницы
$navi->getFirstPage(); // номер первой страницы
$navi->getLastPage(); // номер последней страницы
$navi->getNextPage(); // следующая страница от текущей
$navi->getPrevPage(); // предыдущая страница от текущей, (*5)
По аналогии, для всех методов есть возможность получить готовый объект URL:
~~~ php
$navi->getPageUrl(42); // URL с номером страницы 42
$navi->getFirstPageUrl(); // URL с первой страницей
Функционал постраничности требует, чтобы у Navigator было известно общее количество элементов в выборке и указано
количество элементов на странице., (*6)
~~~ php
$navi->setOnpage(10); // Указываем количество элементов на странице
$navi->setTotal(42); // Указываем количество элементов в выборке
echo $navi->getTotalPages(); // Результат - количество страниц: 5, (*7)
## Сортировка
Navigator позволяет задать допустимые варианты сортировки, а также сформировать ссылки на прямую и обратную сортировку.
~~~ php
$navi = new Navigator($request, new URL('hello'));
$navi->addOrderBy('id'); // Именование и в БД, и в URL совпадает
$navi->addOrderBy('total', 'Количество', 'count(*)'); // В URL будет параметр вида orderby:total, в SQL `count(*)`
После добавления можно получить полный список вариантов сортировки, или отдельные пункты, для формирования списков опций
или ссылок в интерфейсе. Каждый вариант сортировки - это объект OrderBy:, (*8)
~~~ php
$o = $navi->getOrderByOption('total'); // Получили объект
$o->asUrlParameter(); // Значение для подстановки в URL: total - сортировка по-возрастанию
$o->asUrlParameter(false); // _total - сортировка по убыванию
$o->asSQL(); // SQL выражение для сортировки, в данном случае count(*) ASC
$o->asUrl(); // Объект URL, (*9)
Если в адресе содержится параметр сортировки, например `.../orderby:_total/`, можно получить текущий порядок для сортировки:
~~~ php
$navi->getOrderBy();
Если адрес не содержит выбора для сортировки, метод вернет false или способ сортировки по-умолчанию, если он был указан
с помощью метода $navi->setDefaultOrderBy()., (*10)
Выборка элементов, подсчет количества записей
Navigator может сразу обрабатывать данные о сортировке, фильтрах и пагинации, применять их и получать кол-во элементов
в выборке, автоматически расчитывать количество страниц и выдавать соответствующие этим настройкам объекты., (*11)
Если не требуется сложная логика фильтрации, можно воспользоваться настройками, или отнаследоваться от класса и
переопределить соответствующие методы., (*12)
~~~ php
$navi->setCollection('Users'); // Указываем, что используем коллекцию Users
$navi->getTotal(); // Получение общего количества элементов в выборке
$navi->setOnpage(10); // Указываем количество элементов на странице
$navi->getItems(); // Получаем нужный набор элементов, с учетом сортировки и текущей страницы
$navi->each($callable); // Применение $callable к текущей выборке элементов, (*13)
## Фильтрация
Механизм фильтрации работает с помощью назначения фильтров - объектов Filter. Базово предусмотрено три фильтра - Equal,
Between и Like, выполняющие фильтрацию по прямому соответствию, выборке диапазона и условию LIKE. При необходимости
реализации более сложной логики можно добавлять произвольные фильтры с использованием анонимных функций или создавать
свои фильтры наследуясь от класса Filter.
Все фильтры добавляют новые условия (Объект `SQRT\DB\Conditions`) для последующей выборки. Можно задать условия по-умолчанию:
~~~ php
$navi
->conditions(true) // Флаг true указывает что это условия по-умолчанию
->equal('type', 'new')
->greaterOrEqual('age', 18);
Или добавить динамические фильтры:, (*14)
~~~ php
$navi->addFilterEqual('one', 'is_numeric'); // Валидация может выполняться с помощью callable-выражений
$navi->addFilterEqual('two', '/^[a-z]+$/'); // Валидация может выполняться регулярными выражениями
$navi->addFilterBetween('date'); // На свой страх и риск можно обойтись и без валидации
$navi->addFilter(
'some',
null,
function(Navigator $navi, Filter $filter) {
if ($val = $filter->getCleanValue()) {
$navi->conditions()->expr('... some complicated expression ...');
}
}
); // Произвольный фильтр, (*15)
После формирования набора правил, фильтр можно использовать для автоматической обработки запросов и получения
"чистых данных" из URL:
~~~ php
// .../one:42/
echo $navi->getFilter('one')->getCleanValue(); // Результат: 42
// .../one:two/
echo $navi->getFilter('one')->getCleanValue(); // Результат: false
Либо можно получать уже сформированный набор Conditions для SQL запросов с помощью метода processFilters()., (*16)
Callback, указываемый в фильтре, позволяет автоматизировать создание условий для выборки. В функцию передаются как
аргументы объекты Navigator и Filter. После проверки и обработки данных, Callback-функция должна подготовить условие
выборки и передать его в Navigator с помощью метода conditions()., (*17)
Таким образом, в результате работы всех фильтров, получается готовый набор условий, который можно использовать вручную
или автоматически в методах getItems() и countTotal()., (*18)
Изначально предусмотренные фильтры Equal, Between и Like являются наиболее часто используемыми вариантами:
* Equal: прямое соответствие field = value
* Between: значение должно быть в диапазоне field >= column_from и field <= column_to
* Like: генерирует условие [column] LIKE "[value]%", (*19)
Для вышеописанного набора правил, URL и результат будет следующим:, (*20)
~~~ php
URL: /hello/one:1/two:three/date_from:01.01.2014/date_to:31.12.2014/
Результат: one=1 AND two="three AND date >= "01.01.2014" AND date <= "31.12.2014", (*21)
Чистый URL
----------
Важным плюсом работы Navigator`а является то, что вся навигация осуществляется по "чистым адресам". Т.е. если навигатор
настроен на параметры one и two, а в адресе будут указаны мусорные параметры, то в ссылках пагинатора и сортировки
лишних параметров не будет.
~~~ php
$navi = new Navigator($request, new URL('hello', array('one' => 1, 'two' => 2, 'test'=>'me'));
$navi->addFilterEqual('one');
$navi->addFilterEqual('two');
$navi->setPage(42);
echo $navi->getUrlClean()->toString(); // /hello/one:1/two:2/page:42/
Генерация элементов интерфейса
Для сортировки и фильтрации, кроме возможности просто получить объект URL, также предусмотрены методы для формирования
HTML элементов интерфейса. Фильтры будут рендериться с текущими значениями фильтров и сортировки, с учетом валидности
этих данных., (*22)
Для фильтров предусмотрена возможность сгенерировать поле ввода INPUT или SELECT, если у него указаны опции выбора
`$f->setOptions(array(...))`:
~~~ php
$f = $navi->getFilter('one'); // Получаем объект Filter
$f->asInput(); // Генерация тега <input>
$f->asSelect(); // Генерация тега <select> с полным списком опций
Wallogit.com
