Коллекции страниц⚓︎

В Grav наиболее распространенным типом коллекции является список страниц, который может быть определён либо в блоке метаданных страницы, либо в самой Twig-разметке. Наиболее распространенным является определение коллекции в блоке метаданных. Если коллекция определена, она доступна в Twig страницы, чтобы делать с ней всё, что вы пожелаете. Используя методы коллекции страниц или циклически проходя через каждый объект страницы и используя методы или свойства страницы, вы можете делать мощные вещи. Распространенные примеры этого включают отображение списка записей в блоге или отображение модульных подстраниц для визуализации сложного дизайна страницы.

Объект коллекции⚓︎

Когда вы определяете коллекцию в заголовке страницы, вы динамически создаете коллекцию Grav, доступную в Twig страницы. Этот объект коллекции является итерабельным и может рассматриваться как массив, который позволяет вам делать такие вещи, как:

{{ dump(page.collection[page.path]) }}

Пример определения коллекции⚓︎

Пример коллекции, определенной в блоке метаданных страницы:

content:
    items: '@self.children'
    order:
        by: date
        dir: desc
    limit: 10
    pagination: true

Значение content.items в начале страницы указывает Grav собирать коллекцию элементов, и информация, передаваемая ей, определяет, как должна быть построена коллекция.

Это определение создает коллекцию для страницы, которая состоит из всех дочерних страниц, отсортированных по дате и по убыванию, отображаемых вместе с нумерацией страниц, по 10 элементов на странице.

Ссылки пагинации добавляются только в том случае, если установлен и включен плагин Pagination.

Доступ к коллекциям в Twig⚓︎

Когда эта коллекция определена в заголовке, Grav создает коллекцию page.collection, к которой можно получить доступ в шаблоне Twig:

{% for p in page.collection %}
<h2>{{ p.title|e }}</h2>
{{ p.summary|raw }}
{% endfor %}

Это просто перебирает страницы в коллекции с отображением заголовка и резюме.

Вы также можете включить параметр порядка, чтобы изменить порядок страниц по умолчанию:

{% for p in page.collection.order('folder','asc') %}
<h2>{{ p.title|e }}</h2>
{{ p.summary|raw }}
{% endfor %}

Заголовки коллекций⚓︎

Чтобы сообщить Grav, что определенная страница должна быть страницей списков и содержать дочерние страницы, есть ряд переменных, которые можно использовать:

Сводка параметров коллекции⚓︎

Мы рассмотрим их более подробно.

Корневые коллекции⚓︎

@root - Потомки верхнего уровня⚓︎

Это может быть использовано для извлечения верхнего/корневого уровня опубликованных страниц сайта. Особенно полезно для получения элементов, составляющих основную навигацию, например:

content:
    items: '@root.pages'

Также можно использовать псевдоним '@root.children'. Использование '@root' не рекомендуется, так как его значение может измениться в будущем.

@root.descendants - Все страницы⚓︎

Это позволит эффективно получить каждую страницу вашего сайта, поскольку метод рекурсивно перемещается по всем дочерним элементам от корневой страницы вниз и создает коллекцию всех опубликованных страниц сайта:

content:
    items: '@root.descendants'

@root.all - Все страницы и модули⚓︎

Этот метод будет делать то же самое, что и выше, но результат включает все опубликованные страницы и модули сайта.

content:
    items: '@root.all'

Самостоятельные коллекции⚓︎

@self.page - Только текущая страница⚓︎

Это вернет коллекцию, содержащую только текущую страницу.

content:
    items: '@self.page'

Также можно использовать псевдоним '@self.self'.

@self.parent - Родительская страница текущей страницы⚓︎

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

content:
    items: '@self.parent'

@self.siblings - Страницы того же уровня, что и текущая⚓︎

Эта коллекция будет собирать все опубликованные страницы на том же уровне текущей страницы, за исключением текущей:

content:
    items: '@self.siblings'

@self.children - Дочерние страницы текущей⚓︎

Используется для перечисления опубликованных дочерних элементов текущей страницы:

content:
    items: '@self.children'

Также можно использовать псевдоним '@self.pages'. Использование '@self' не рекомендуется, так как его значение может измениться в будущем.

@self.modules - Модули текущей страницы⚓︎

Этот метод извлекает только опубликованные модули текущей страницы. (_features, _showcase и т. д.):

content:
    items: '@self.modules'

Использование псевдонима '@self.modular' устарело.

@self.all - Дочерние страницы и модули текущей страницы⚓︎

Этот метод извлекает только опубликованные дочерние элементы и модули текущей страницы:

content:
    items: '@self.all'

@self.descendants - Дочерние страницы + все потомки текущей страницы⚓︎

Подобно .children, коллекция .descendants извлечет все опубликованные дочерние элементы, но вдобавок ещё и рекурсивно получит всех потомков:

content:
    items: '@self.descendants'

Коллекции страниц⚓︎

@page.page - Коллекция с включением только указанной страницы⚓︎

Эта коллекция принимает в качестве аргумента служебный маршрут страницы и возвращает коллекцию, содержащую эту страницу (если это опубликованная страница):

content:
    items:
      '@page.page': '/blog'

Также можно использовать псевдоним '@page.self': '/blog'.

@page.parent - Родительская страница конкретной страницы⚓︎

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

content:
    items:
      '@page.parent': '/blog'

@page.siblings - Страницы того же уровня, что и указанная⚓︎

Эта коллекция соберет все опубликованные страницы на том же уровне, что и текущая, исключая её саму:

content:
    items:
        '@page.siblings': '/blog'

@page.children - Дочерние элементы указанной страницы⚓︎

Эта коллекция принимает в качестве аргумента служебный маршрут страницы и возвращает все опубликованные дочерние элементы этой страницы:

content:
    items:
      '@page.children': '/blog'

Также можно использовать псевдоним '@page.pages': '/blog'. Использование '@page': '/blog' не рекомендуется, так как его значение может измениться в будущем.

@page.modules - Модули указанной страницы⚓︎

Эта коллекция принимает в качестве аргумента служебный маршрут страницы и возвращает все опубликованные модули этой страницы:

content:
    items:
      '@page.modules': '/blog'

Использование псевдонима '@page.modular': '/blog' устарело.

@page.all - Дочерние элементы и модули указанной страницы⚓︎

Этот метод извлекает только опубликованные дочерние элементы и модули конкретной страницы:

content:
    items:
      '@page.all': '/blog'

@page.descendants - Коллекция дочерних элементов и всех потомков указанной страницы⚓︎

Эта коллекция принимает в качестве аргумента служебный маршрут страницы и возвращает все опубликованные дочерние элементы и всех потомков этой страницы:

content:
    items:
      '@page.descendants': '/blog'

Коллекции таксономии⚓︎

content:
   items:
      '@taxonomy.tag': foo

С опцией @taxonomy вы можете использовать мощную функциональность таксономии Grav. Именно здесь вступает в действие переменная taxonomy в файле конфигурации сайта. Должно быть определение для таксономии, определенной в этом файле конфигурации для Grav, чтобы интерпретировать ссылку на страницу как действительную.

Установив @taxonomy.tag: foo, Grav найдет все опубликованные страницы в папке /user/pages, имеющие tag: foo в своей переменной таксономии:

content:
    items:
       '@taxonomy.tag': [foo, bar]

Переменная content.items может принимать массив таксономий и собирать все страницы, удовлетворяющие этим правилам. Будут собраны опубликованные страницы, которые имеют как тег foo, так и тег bar. В главе Таксономия эта концепция рассмотрена более подробно.

Если у вас есть несколько переменных в одном родителе для установки, вы можете сделать это с помощью встроенного метода, но для простоты мы рекомендуем использовать стандартный метод. Вот пример:

content:
  items:
    '@taxonomy':
      category: [blog, featured]
      tag: [foo, bar]

На каждом уровне иерархии перед переменной добавляются два пробела. YAML позволит вам использовать столько пробелов, сколько вы хотите, но два - стандартная практика. В приведенном выше примере переменные category и tag установлены в @taxonomy.

Коллекции страниц будут автоматически отфильтрованы по таксономии, если она была указана в URL (например, /archive/category:news). Это позволяет создать один шаблон архива блога, но динамически фильтровать коллекцию с помощью URL. Если ваша коллекция страниц должна игнорировать таксономию, установленную в URL, используйте флаг url_taxonomy_filters: false, чтобы отключить эту функцию.

Сложные коллекции⚓︎

Вы также можете предоставить несколько сложных определений коллекции, и результирующая коллекция будет суммой всех страниц, найденных из каждого из определений коллекции. Например:

content:
  items:
    - '@self.children'
    - '@taxonomy':
         category: [blog, featured]

Кроме того, можно фильтровать коллекцию, используя filter: type: value. Тип может быть любым из следующих: published, visible, page, module, routable. Они соответствуют специфичным для коллекций методам, и вы можете использовать несколько из них для фильтрации вашей коллекции. Каждый из них может иметь значение true или false. Кроме того, существует type, который принимает одно имя-шаблона, types, которое принимает массив имен-шаблонов, и access, который принимает массив уровней доступа. Например:

 content:
  items: '@self.siblings'
  filter:
    visible: true
    type: 'blog'
    access: ['site.login']

Тип также может быть отрицательным: non-published, non-visible, non-page (=module), non-module (=page) и non-routable, но лучше использовать положительную версию типа со значением false.

 content:
  items: '@self.children'
  filter:
    published: false

Варианты сортировки⚓︎

content:
    order:
        by: date
        dir: desc
    limit: 5
    pagination: true

Порядок подстраниц соответствует тем же правилам, что и порядок папок. Доступные опции:

Переменнаяcontent.order.dir контролирует направление сортировки. Допустимые значения: desc или asc.

content:
    order:
        by: default
        custom:
            - _showcase
            - _highlights
            - _callout
            - _features
    limit: 5
    pagination: true

В приведенной выше конфигурации вы можете видеть, что content.order.custom определяет пользовательский порядок для указания того, что на странице сначала идет витрина, затем секция основных моментов и т. д. Обратите внимание, что если страница не указана в списке пользовательской сортировки, то Grav возвращается к content.order.by для неуказанных страниц.

Если на странице есть настраиваемый ярлык, вы должны использовать его в списке content.order.custom.

content.pagination — это простой логический флаг, который используется плагинами и т. д. Чтобы знать, следует ли инициализировать разбиение на страницы для этой коллекции. content.limit — количество элементов, отображаемых на странице при включенной нумерации страниц.

Диапазон дат⚓︎

Существует также возможность фильтрации страниц по диапазону дат:

content:
    items: '@self.children'
    dateRange:
        start: 1/1/2014
        end: 1/1/2015

Вы можете использовать любой строковый формат даты, поддерживаемый strtotime(), например 6 weeks или last Monday, а также более традиционные даты, такие как 01/23/2014 или 23 января 2014. DateRange отфильтрует любые страницы, у которых есть дата за пределами предоставленного диапазона. Даты начала и конца являются необязательными, но следует указать хотя бы одну.

Несколько коллекций⚓︎

Когда вы создаете коллекцию с content: items: в вашем YAML, вы определяете одну коллекцию на основе нескольких условий. Однако Grav позволяет создавать произвольный набор коллекций на странице, вам просто нужно создать ещё одну:

content:
    items: '@self.children'
    order:
        by: date
        dir: desc
    limit: 10
    pagination: true

fruit:
    items:
       '@taxonomy.tag': [fruit]

Это устанавливает 2 коллекции для этой страницы. Первая использует коллекцию по умолчанию content, а вторая определяет коллекцию на основе таксономии под названием fruit. Для доступа к этим двум коллекциям через Twig вы можете использовать следующий синтаксис:

{% set default_collection = page.collection %}
{% set fruit_collection = page.collection('fruit') %}

Методы объекта коллекции⚓︎

Доступные итерируемые методы:

Также есть несколько полезных методов, специфичных для коллекции:

Вот пример из docs.html.twig темы Learn2, который определяет коллекцию на основе таксономии (и, возможно, тегов, если они существуют) и использует методы Collection::isFirst и Collection::isLast для навигации по страницам:

{% set tags = page.taxonomy.tag %}
{% if tags %}
    {% set progress = page.collection({'items':{'@taxonomy':{'category': 'docs', 'tag': tags}},'order': {'by': 'default', 'dir': 'asc'}}) %}
{% else %}
    {% set progress = page.collection({'items':{'@taxonomy':{'category': 'docs'}},'order': {'by': 'default', 'dir': 'asc'}}) %}
{% endif %}

{% block navigation %}
        <div id="navigation">
        {% if not progress.isFirst(page.path) %}
            <a class="nav nav-prev" href="{{ progress.nextSibling(page.path).url|e }}"> <i class="fa fa-chevron-left"></i></a>
        {% endif %}

        {% if not progress.isLast(page.path) %}
            <a class="nav nav-next" href="{{ progress.prevSibling(page.path).url|e }}"><i class="fa fa-chevron-right"></i></a>
        {% endif %}
        </div>
{% endblock %}

nextSibling() — вверх по списку, prevSibling() — вниз по списку, вот как это работает:

Предположим, что у вас есть страницы:

Project A
Project B
Project C

Вы находитесь на странице «Проект A», предыдущая страница - это «Проект B». При переходе на страницу «Проект B» предыдущей станет «Проект C», а следующей — «Проект A».

Программные коллекции⚓︎

Вы можете получить полный контроль над коллекциями прямо из PHP в плагинах, темах Grav или даже из Twig. Это более жестко запрограммированный подход по сравнению с определением их во внешнем оформлении страницы, но он также позволяет использовать более сложную и гибкую логику коллекций.

PHP-коллекции⚓︎

Вы можете выполнить расширенную логику сбора с помощью PHP, например:

<?php

$collection = new Collection($pages);
$collection->setParams(['taxonomies' => ['tag' => ['dog', 'cat']]])->dateRange('01/01/2016', '12/31/2016')->published()->ofType('blog-item')->order('date', 'desc');

$titles = [];

foreach ($collection as $page) {
    $titles[] = $page->title();
}

Функция order() может также, в дополнение к параметрам by и dir, принимать параметры manual и sort_flags. Это задокументировано выше. Вы также можете использовать тот же метод evaluate(), который используют коллекции страниц на основе блока метаданных:

<?php

$page = Grav::instance()['page'];
$collection = $page->evaluate(['@page.children' => '/blog', '@taxonomy.tag' => 'photography']);
$ordered_collection = $collection->order('date', 'desc');

И ещё один пример индивидуальной сортировки:

<?php

$ordered_collection = $collection->order('header.price','asc',null,SORT_NUMERIC);

Вы также можете сделать то же самое непосредственно в шаблонах Twig:

{% set collection = page.evaluate([{'@page.children':'/blog', '@taxonomy.tag':'photography'}]) %}
{% set ordered_collection = collection.order('date','desc') %}

Расширенные коллекции⚓︎

По умолчанию, когда вы вызываете page.collection() в Twig страницы, имеющей коллекцию, определенную в заголовке, Grav ищет коллекцию с названием content. Это позволяет определять несколько коллекций, но вы можете пойти дальше.

Если вам нужно программно сгенерировать коллекцию, вы можете сделать это, вызвав page.collection() и передав массив в том же формате, что и определение коллекции заголовков страницы. Например:

{% set options = { items: {'@page.children': '/my/pages'}, 'limit': 5, 'order': {'by': 'date', 'dir': 'desc'}, 'pagination': true } %}
{% set my_collection = page.collection(options) %}

<ul>
    {% for p in my_collection %}
        <li>{{ p.title|e }}</li>
    {% endfor %}
</ul>

Генерация меню для всего сайта (вам необходимо установить свойство menu в блоке метаданных страницы):

---
title: Home
menu: Home
---

{% set options = { items: {'@root.descendants':''}, 'order': {'by': 'folder', 'dir': 'asc'}} %}
{% set my_collection = page.collection(options) %}

{% for p in my_collection %}
{% if p.header.menu %}
    <ul>
    {% if page.slug == p.slug %}
        <li class="{{ p.slug|e }} active"><span>{{ p.menu|e }}</span></li>
    {% else %}
        <li class="{{ p.slug|e }}"><a href="{{ p.url|e }}">{{ p.menu|e }}</a></li>
    {% endif %}
    </ul>
{% endif %}
{% endfor %}

Пагинация с расширенными коллекциями⚓︎

Часто мы слышим вопрос о том, как включить разбиение на страницы для пользовательских коллекций. Пагинация - это плагин pagination, который можно установить через GPM. После установки он работает «из коробки» с коллекциями, настроенными на странице, но ничего не знает о пользовательских коллекциях, созданных в Twig. Чтобы упростить этот процесс, разбиение на страницы поставляется с собственной функцией Twig, называемой paginate(), которая обеспечит необходимую функциональность разбивки на страницы.

После того, как мы передаем коллекцию и ограничение функции paginate(), нам также необходимо передать информацию о разбиении на страницы непосредственно в шаблон partials/pagination.html.twig для правильного отображения.

{% set options = { items: {'@root.descendants':''}, 'order': {'by': 'folder', 'dir': 'asc'}} %}
{% set my_collection = page.collection(options) %}
{% do paginate( my_collection, 5 ) %}

{% for p in my_collection %}
    <ul>
        {% if page.slug == p.slug %}
            <li class="{{ p.slug|e }} active"><span>{{ p.menu|e }}</span></li>
        {% else %}
            <li class="{{ p.slug|e }}"><a href="{{ p.url|e }}">{{ p.menu|e }}</a></li>
        {% endif %}
    </ul>
{% endfor %}

{% include 'partials/pagination.html.twig' with {'base_url':page.url, 'pagination':my_collection.params.pagination} %}

Пользовательская обработка коллекции с событием onCollectionProcessed()⚓︎

Бывают случаи, когда вариантов событий просто недостаточно. Когда вы хотите получить коллекцию, но затем продолжите манипулировать коллекцией на основе чего-то очень нестандартного. Представьте себе, если хотите, вариант использования, в котором у вас есть то, что кажется довольно стандартным списком блогов, но ваш клиент хочет иметь точный контроль над тем, что отображается в списке. Они хотят иметь настраиваемый переключатель для каждого элемента блога, который позволяет им удалить его из списка, но при этом опубликовать его и получить по прямой ссылке.

Чтобы это произошло, мы можем просто добавить настраиваемую опцию display_in_listing: false в заголовок страницы для элемента:

---
title: 'My Story'
date: '13:34 04/14/2020'
taxonomy:
    tag:
        - journal
display_in_listing: false
---
...

Проблема в том, что нет способа определить или включить этот фильтр при определении коллекции на странице листинга. Вероятно, это определяется примерно так:

---
menu: News
title: 'My Blog'
content:
    items:
        - self@.children
    order:
        by: date
        dir: desc
    limit: 8
    pagination: true
    url_taxonomy_filters: true
---
...

Таким образом, коллекция просто определяется директивой self@.chidren для получения всех опубликованных дочерних элементов текущей страницы. Так что насчет тех страниц, у которых установлен параметр display_in_listing: false? Нам нужно проделать дополнительную работу с этой коллекцией, прежде чем она будет возвращена, чтобы убедиться, что мы удалим все элементы, которые мы не хотим видеть. Для этого мы можем использовать событие onCollectionProcessed() в настраиваемом плагине. Нам нужно добавить слушателя:

<?php

    public static function getSubscribedEvents(): array
    {
        return [
            ['autoload', 100000],
            'onPluginsInitialized' => ['onPluginsInitialized', 0],
            'onCollectionProcessed' => ['onCollectionProcessed', 10]
        ];
    }

Затем нам нужно определить метод и перебрать элементы коллекции, ища любые страницы с этим набором полей display_in_listing:, а затем удалить его, если он равен false:

<?php

    /**
     * Remove any page from collection with display_in_listing: false|0
     *
     * @param Event $event
     */
    public function onCollectionProcessed(Event $event): void
    {
        /** @var Collection $collection */
        $collection = $event['collection'];

        foreach ($collection as $item) {
            $display_in_listing = $item->header()->display_in_listing ?? true;
            if ((bool) $display_in_listing === false) {
                $collection->remove($item->path());
            }
        }

    }

Теперь в вашей коллекции есть правильные элементы, и все другие плагины или шаблоны Twig, которые полагаются на эту коллекцию, будут видеть эту измененную коллекцию, поэтому такие вещи, как разбиение на страницы, будут работать должным образом.