Сниппеты и TV-поля

Шаблон задаёт вид страницы, чанк хранит повторяющийся кусок разметки. Остались вещи, которые нельзя ни нарисовать заранее, ни скопировать: меню, которое само знает обо всех разделах, и картинка-анонс, которой у страницы по умолчанию нет. Этим занимаются сниппеты и TV-поля.

Сниппет — кусок программы

Сниппет (snippet, «фрагмент») — небольшая программа на PHP, которая запускается в момент сборки страницы и возвращает готовый HTML. Вызывается так же коротко, как чанк, только скобки другие — квадратные:

<nav class="main-nav">
  [[DocLister? &parents=`3` &tpl=`menu-item`]]
</nav>

Что здесь происходит: движок дошёл до этой строки, запустил сниппет DocLister, передал ему два параметра — откуда брать страницы и каким чанком рисовать каждую. Сниппет сходил в базу, собрал детей третьего раздела, обернул каждого в разметку чанка и вернул готовый кусок HTML. На странице этот вызов не виден вообще — вместо него стоит результат.

Разница с чанком ровно в одном слове. Чанк подставляется, сниппет выполняется. Чанк вернёт то же самое на любой странице; сниппет каждый раз считает заново и на разных страницах вернёт разное.

Писать свои сниппеты не придётся

Хорошая новость для человека, который не знает PHP: девять задач из десяти закрываются готовыми сниппетами. Они ставятся из админки, а от вас требуется только правильно их вызвать.

Каждый из них настраивается параметрами — теми самыми &имя=`значение` после знака вопроса. Их бывает много, но выучивать нечего: список параметров лежит в документации сниппета, а нужны обычно три-четыре.

Другие скобки и кэш

Evolution запоминает собранные страницы, чтобы не пересобирать их на каждое открытие. Обычно это хорошо: меню меняется редко, и считать его сто раз незачем.

Но есть вещи, которые обязаны быть свежими всегда: результат поиска, форма, вывод случайной цитаты. Такой вызов пишут в других скобках — вместо [[Сниппет]]. Это и значит «не бери из памяти, посчитай сейчас».

[[DocLister? &parents=`3`]]   <!-- меню: можно из кэша -->
   <!-- свежий список: заново -->



  

  
  

    Это поле оставьте пустым
    
  

  

    Как вас зовут
    
    
  

  

    Адрес почты
    
    

      Нужен только для ответа. Никаких рассылок.
    
    
  

  

    Сообщение
    
    
  

  

    
    
      Соглашаюсь, что имя и адрес почты нужны только для ответа
      на это сообщение.
    
    
  

  

    
      
      Отправить
    
  

  
  


       <!-- форма: всегда заново -->

TV-поле — своё поле у страницы

У каждой страницы есть готовый набор полей: заголовок, текст, описание. Их хватает ровно до первой задачи из жизни. Например, карточке мануала на хабе нужны картинка и время чтения. Куда их положить? В текст нельзя — он идёт в статью целиком.

Для этого и придуманы TV-поля (template variables, «переменные шаблона»). Вы создаёте новое поле в админке, привязываете его к нужным шаблонам — и в форме редактирования страницы появляется ещё одно поле для заполнения.

Вызывается TV-поле так же, как встроенное, — по имени в скобках со звёздочками. Отличить его от родного поля по коду нельзя, и это удобно:

<article class="card">
  <img src="[*cover*]" alt="" width="640" height="360" loading="lazy">
  <h3 class="card__title">[*pagetitle*]</h3>
  <p class="card__text">[*introtext*]</p>
  <span class="chip">[*reading_time*] мин</span>
</article>

Здесь [*pagetitle*] и [*introtext*] — встроенные поля, а [*cover*] и [*reading_time*] — придуманные мной TV. В админке они выглядят как обычные поля формы: у первого — кнопка выбора файла, у второго — строка ввода.

У TV есть тип

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

Как это выглядит в админке

1. Сниппеты: свои и чужие в одном списке

   Закладка «Сниппеты». Сверху — семейство DocLister, поставленное из каталога расширений, ниже — четыре своих. Имя из этого списка и пишут в квадратных скобках.

   Увеличить

2. TV-поля заводятся один раз на сайт

   Закладка «Параметры (TV)». Каждая строка — новое поле в карточке страницы. У этого сайта их шесть: тексты для мессенджера, три строки условий мануала и обстановка вокруг статьи.

   Увеличить

3. Заполняются они в карточке страницы

   Заведённое поле появляется у страницы отдельным блоком «Параметры (TV)» — с тем названием и пояснением, которые вы ему дали. Под названием видно имя, которым поле зовут в шаблоне.

   Увеличить

Четыре понятия рядом

Теперь можно собрать всё вместе. Эта таблица — короткий ответ на вопрос «что из них что», ради которого и затевался этап.

Что я спросил у нейросети

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

Получилось с третьего раза, и это нормально: первые два ответа были для MODX Revolution, где синтаксис другой. Помогла приписка «именно Evolution CMS, не Revolution» — в запросе выше она стоит с самого начала.