Переменная шаблона (TV) является настраиваемым полем, или, точнее, это настраиваемое поле для ресурса MODx. TV используются для расширения атрибутов по умолчанию, доступных для ресурса (например, для страницы или веб-ссылки). Нормальный MODx ресурс имеет определенное количество полей по умолчанию: pagetitle, content, description и т.д. Если вам нужно добавить некоторые пользовательские поля на ваши страницы, например второе поле контента или выпадающий список названий месяцев, или любой другой вид пользовательских данных, вы можете сделать это, добавив TV в шаблон. MODx позволяет иметь практически неограниченное количество TV.

Когда ресурс отображается в браузере, TV заменяется на фактическое значение, введенное пользователем. TV используются только в тех шаблонах, для которых они назначены.

Выходные фильтры сделают TV более удобным для пользователей, они помогут добавить специальные визуальные эффекты на своих веб-сайтах. С помощью всего лишь нескольких кликов мыши, вы можете добавить изображения, URL или свой способ парсинга документа на ваш сайт.

Использование TV

Допустим есть TV с именем 'bio' – мы указали при создании, что это текстовый TV и отнесли его к  шаблон ‘Biography Pages’. Для того, чтобы показать наш TV на странице, необходимо сделать вызов в шаблоне:

[ [*bio] ]

Кроме того, вы можете передавать параметры в TV. Допустим, у нас есть TV под названием 'intromsg' с содержимым:

Hello [ [+name] ], you have [ [+messageCount] ] messages.

Вы можете передать параметры, аналогично чанкам:

[ [*intromsg?name=`George` &messageCount=`123`] ]

На выходе мы получим:

Hello George, you have 123 messages.

Выходные фильтры – это великолепный инструмент манипулированием нашими TV. К слову, если вы хотите вывести только 100 символов из значения TV, то это можно сделать выходным фильтром ‘limit’:

[ [*bioMessage:limit=`100`] ]

Об фильтрах мы поговорим чуть позже.

Создание TV-параметра

  1. Заходим в панель управления MODx
  2. Добавляем TV

    В левой части панели управления переходим на вкладку Элементы, и нажимаем левым кликом на кнопку с иконкой-телевизором.

  3. Заполняем общую информацию

    • Имя: будет использоваться при вызове TV, т.е. bio = . Оно должно быть УНИКАЛЬНЫМ!
    • Заголовок: будет отображаться при редактировании содержания TV.
    • Описание: будет отображаться при редактировании TV.
    • Категория: создаст новую вкладку при редактировании TV.
    • Сортировка: если вы используете более одного TV, это будет определять, какие появляются в верхней части (1 = верх, большие номера ниже)

  4. Параметры ввода

    Следующий шаг – переход на вкладку ‘Параметры ввода’. Здесь нам нужно выбрать как будет отображаться наш TV при вводе:

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

  5. Настройка доступа к TV

    Перейдите на вкладку ‘Доступно для шаблонов’: необходимо определить, какой шаблон (ы) на самом деле будет использовать это TV и выбрать их.

    Каждый раз, когда вы создаете ресурс, который использует шаблон, к которому TV был прикреплен, TV будет доступен для редактирования. Убедитесь, что вы прикрепили TV к, по крайней мере, одному шаблону.

  6. Сохраняем TV

    Когда вы все заполнили, вы можете сохранить TV.

  7. Использование

    Теперь, когда вы создали свой TV и прикрепили его к шаблону, можно создать ресурс MODx (например, щелкните правой кнопкой мыши в дереве документа и выберите Создать -> Создать дочерний ресурс). Выберите шаблон, который использует этот TV.

  8. Редактирование значения

    Как только ваш MODx ресурс (т.е. страница) использует шаблон, содержащий переменную шаблона, вы можете добавить ему значение, нажав на вкладке "Дополнительные поля" страницы.

Форматирование вывода

Далее, мы выберем выходные опции рендеринга. Мы выберем TV ’date’:

Здесь мы можем настроить формат вывода даты.

Bindings

Применительно к TV, источник данных – это расположение информации, которая должна быть показана. Источники данных могут быть следующие:

  • внешний файл, который отправляется через FTP на сервер
  • таблица БД, доступных для MODx
  • ресурсы в дереве ресурсов
  • чанк в дереве элементов
  • результат выполнения PHP-кода

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

  • @FILE путь к файлу
  • @RESOURCE идентификатор ресурса
  • @CHUNK имя чанка
  • @SELECT sql запрос
  • @EVAL php-код
  • @DIRECTORY путь относительно корня
  • @INLINE доступно в некоторых сниппетах (например, getResources), это специфический чанк, написанный в одну строку при вызове.

Chunk bindings

@CHUNK Binding возвращает разобранный чанк, когда @CHUNK используется в переменной шаблона (TV).

Другими словами, если @CHUNK hello является значением TV называемой MyChunk, следующий тег в шаблоне или в содержимом ресурса, поле ресурса будет заменен содержимым чанка Hello:

[ [*MyChunk] ]

Синтаксис

@CHUNK chunk_name

DIRECTORY Binding

DIRECTORY Binding считывает содержимое директории. Это может действительно полезно, когда вы связываете со списком виджетов, например, если вы хотите дать пользователю список логотипа на выбор для страницы, или выбрать какой файл mp3 играет на определенной странице. ПОМНИТЕ: он возвращает все содержимое каталога, включая все файлы и все каталоги - с единственным исключением каталогов префикса с периодом.

При создании переменной шаблона, поместите следующий текст в поле ввода значения:

@DIRECTORY /path/to/some_directory

Часто, это сочетается с входным типом: "Выпадающий список меню", чтобы позволить пользователю выбрать файл из списка.

EVAL Binding

Эту связку нужно использовать при применении необходимых мер безопасности.

@EVAL php_code_here

Для применения следует просто написать php-код:

@EVAL return "The time stamp is now ".time();

FILE Binding

Данная связка возвращает содержимое внешнего файла.

@FILE file_path

Связывает переменную в файл, где file_path это путь и имя файла. Возвращаемое значение является строкой, содержащей содержание файла. Путь к файлу - абсолютный путь от корня сервера или конкретной установки.

Команда @FILE очень полезна в тех случаях, когда мы могли хотим, чтобы генерировались данные, которые доступны в файле. Используя | | и == символы в качестве разделителя мы могли взаимодействовать с любым внешним приложением базы данных.

RESOURCE Binding

Данная связка возвращает сгенерированное содержимое ресурса.

@RESOURCE resource_id

Связывает TV с ресурсом, где resource_id - идентификатор ресурса. Возвращаемое значение - строка, содержащая содержание ресурса.

@RESOURCE 12

SELECT Binding

Данная связка возвращает ответ на запрос в БД.

@SELECT `username` AS `name`,`id` FROM `[ [+PREFIX] ]users` WHERE `active` = 1

Входные типы данных для TV

  1. Auto-Tag

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

    Для вывода тегов таким образом, чтобы каждый тег был ссылкой на определенный ресурс и принимает тег в качестве параметра GET, вы можете использовать выходной фильтр (сниппета) следующим образом:

    			if ($input == '') { return 'Error'; } // Если TV пустой, то ошибка
    			$tags = explode(', ',$input); // создаем массив тегов по разделителю ,
    			foreach ($tags as $key => $value) { // Цикл по массиву тегов
    			  $output[] = ''.$value.''; // делаем ссылки на ресурс
    			}
    			return implode(', ',$output); // объединяем выходной массив
    		
  2. Checkbox

    Базовое использование - просто определить поле в виде флажка. Вы можете управлять, будет ли или нет checkbox установлен по умолчанию или нет, манипулируя "входным значением" и "Значением по умолчанию”.

    По умолчанию отмечен

    • Input Option Values: My Option==1
    • Default Value: 1

    По умолчанию не отмечен:

    • Input Option Values: My Option==1
    • Default Value: 0

    Вы можете задать несколько ключей и значений с помощью разделителя (двойная вертикальная черта):

    option1==value1||option2==value2

  3. Date

    Позволяет выбрать дату и время.

    Значение по умолчанию

    Функция

    yesterday

    Вчерашний день, время 12:00pm

    today

    Сегодняшний день, время 12:00pm

    now

    Текущая дата и время

    tomorrow

    Завтрашний день, время 12:00pm

    +X

    X – часы от текущей даты, например, +72 значит "3 от текущего момента"

    -X

    X – часы от текущей даты, например, -72 значит "3 дня"

  4. Выпадающий список

    Установите входные значения опций в формате option1 == значение1 | | опция2 == значение2 | | option3 == значение3. Убедитесь в том, что вы выбрали тип вывода с разделителями (или другой по вашему вкусу). Вы также можете использовать @SELECT, чтобы выбрать 2 колонки, например:

    @SELECT name, value FROM your_table

    Также существует список ресурсов.

  5. Email

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

  6. File

    Создает форму ввода - файл для загрузки на сервер. Файлы могут быть загружены через файловый менеджер MODx. Вы можете объявить значение по умолчанию, указав путь к файлу.

    Будьте особенно внимательны к относительным путям к файлам при использовании дружественных URL.

  7. Hidden

    Скрытое поле не появляется в менеджере, так что это должно быть что-то редкое. Вы можете установить значение по умолчанию, которые могут быть извлечены на всех страницах, используя эту переменную. Другая возможность заключается в хранении фрагмента, который берет- ID страницы в качестве входных данных.

  8. Текстовый редактор

    Это дает вам небольшой редактор WSYIWYG для поля. Это точно походит на крупных текстовых полей с форматированием.

  9. Изображение

    Создает форму ввода изображения для просмотра файлов на сервер. Файлы могут быть загружены через файловый менеджер MODx.

  10. Radio

    Вывод подобен Checkbox