README

该组件允许自动化或简化列表元素的分页、排序和筛选工作。

初始化 Navigator 对象，传递 Request 和 Manager 对象。

$navi = new Navigator($request, $manager);

分页

Navigator 对象提供了一组方法，用于获取第一页、最后一页、下一页、上一页，以及为这些页面快速生成 URL 对象。

$navi->getPage(); // получение номера текущей страницы
$navi->getFirstPage(); // номер первой страницы
$navi->getLastPage(); // номер последней страницы
$navi->getNextPage(); // следующая страница от текущей
$navi->getPrevPage(); // предыдущая страница от текущей

类似地，所有方法都有获取 URL 对象的选项

$navi->getPageUrl(42); // URL с номером страницы 42
$navi->getFirstPageUrl(); // URL с первой страницей

分页功能要求 Navigator 了解选择中的总元素数量和每页元素数量。

$navi->setOnpage(10); // Указываем количество элементов на странице
$navi->setTotal(42); // Указываем количество элементов в выборке
echo $navi->getTotalPages(); // Результат - количество страниц: 5

排序

Navigator 允许指定排序选项，并生成直接和反向排序的链接。

$navi = new Navigator($request, new URL('hello'));
$navi->addOrderBy('id'); // Именование и в БД, и в URL совпадает
$navi->addOrderBy('total', 'Количество', 'count(*)'); // В URL будет параметр вида orderby:total, в SQL `count(*)`

添加后，可以获取完整的排序选项列表，或单独的项目，以生成界面中的选项或链接列表。每个排序选项都是一个 OrderBy 对象

$o = $navi->getOrderByOption('total'); // Получили объект
$o->asUrlParameter(); // Значение для подстановки в URL: total - сортировка по-возрастанию
$o->asUrlParameter(false); // _total - сортировка по убыванию
$o->asSQL(); // SQL выражение для сортировки, в данном случае count(*) ASC
$o->asUrl(); // Объект URL

如果地址中包含排序参数，例如 .../orderby:_total/，则可以获取当前的排序顺序

$navi->getOrderBy();

如果地址不包含排序选择，则方法将返回 false 或默认排序方式，如果已通过方法 $navi->setDefaultOrderBy() 指定。

选择元素，计算记录数量

Navigator 可以立即处理排序、筛选和分页数据，应用它们，并获取选择中的元素数量，自动计算页数，并输出相应的对象。

如果不需要复杂的筛选逻辑，可以使用设置，或从类继承并重写相应的方法。

$navi->setCollection('Users'); // Указываем, что используем коллекцию Users
$navi->getTotal(); // Получение общего количества элементов в выборке
$navi->setOnpage(10); // Указываем количество элементов на странице
$navi->getItems(); // Получаем нужный набор элементов, с учетом сортировки и текущей страницы
$navi->each($callable); // Применение $callable к текущей выборке элементов

筛选

筛选机制通过分配 Filter 对象（筛选器）来实现。基本上预定义了三个筛选器 - Equal、Between 和 Like，它们执行直接匹配、范围选择和 LIKE 条件筛选。如果需要实现更复杂的逻辑，可以添加自定义筛选器，使用匿名函数或通过从 Filter 类继承来创建自己的筛选器。

所有筛选器都会添加新的条件（对象 SQRT\DB\Conditions）以供后续选择。可以设置默认条件

$navi
  ->conditions(true) // Флаг true указывает что это условия по-умолчанию
  ->equal('type', 'new')
  ->greaterOrEqual('age', 18);

或添加动态筛选器

$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 ...');
    }
  }
); // Произвольный фильтр

在形成规则集之后，可以使用筛选器自动处理请求并从 URL 获取“纯净数据”。

// .../one:42/
echo $navi->getFilter('one')->getCleanValue(); // Результат: 42

// .../one:two/
echo $navi->getFilter('one')->getCleanValue(); // Результат: false

或者，可以使用 processFilters() 方法获取 SQL 查询的已形成 Conditions 集合。

筛选器中指定的回调函数允许自动化创建选择条件。该函数接收 Navigator 和 Filter 对象作为参数。在检查和处理数据后，Callback 函数应准备选择条件，并通过 conditions() 方法将其传递给 Navigator。

因此，通过所有筛选器的处理，可以得到一个可手动使用或自动在 getItems() 和 countTotal() 方法中使用的条件集合。

最初预定义的筛选器 Equal、Between 和 Like 是最常用的选项

• Equal: field = value 的直接匹配
• Between: 值应在 field >= column_from 和 field <= column_to 范围内
• Like: 生成 [column] LIKE "[value]%" 条件

对于上述规则集，URL 和结果将是以下内容

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"

纯净 URL

Navigator 的工作的一个重要优点是所有导航都通过“纯净地址”进行。也就是说，如果导航器设置为参数 one 和 two，而在地址中指明了垃圾参数，则分页器和排序链接中不会出现多余的参数。

$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 元素的方法，用于排序和筛选。过滤器将使用当前筛选值和排序值进行渲染，同时考虑数据的有效性。

生成 SELECT

$navi->getOrderByAsSelect(); // Генерация тега <select> с полным списком опций

对于筛选器，如果已指定选项选择（$f->setOptions(array(...))），则可以生成输入字段 INPUT 或 SELECT。

$f = $navi->getFilter('one'); // Получаем объект Filter
$f->asInput(); // Генерация тега <input>
$f->asSelect(); // Генерация тега <select> с полным списком опций