Документация MIGX

Здесь представлен перевод статей с rtfm.modx.com, а также добавлен из некоторых других источников. Если вы нашли ошибку или опечатку, напишите об этом в комментарии.

• Что такое MIGX?
• Как работает специльный тип дополнительных полей (TV) MIGX
• Создание первого TV MIGX
  • Шаг 1: Создайте TV MIGX
  • Шаг 2: Настроить поля ввода MIGX
  • Шаг 2.1: Вкладки формы
  • Ключи для "Вкладки форм"
  • Шаг 2.2: Разметка колонок
  • Ключи для "Разметки колонок"
• Ввод данных
  • Шаг 1: Установка
  • Шаг 2: Ввод данных
  • Шаг 3: Изменение данных
  • Шаг 4: Упорядочивание данных
• Вывод данных через getImageList
  • Отображение элементов MIGX
  • Пример использования getImageList
  • Вывод MIGX TV внутри шаблона getResources
  • Параметры сниппета getImageList
  • Доступные плейсхолдеры в шаблоне вывода getImageList
• Продвинутое использование
  • Динамическая замена шаблона
• Еще примеры использования MIGX:
  • Слайдер MIGX — Пример вызова с картинкой из специального источника файлов
  • Пример вызова с сортировкой и лимитом
  • Вариант реализации MIGX (выпадающий список из системной настройки)
  • Как не выводить пустой getImageList. Использование wrapperTpl — альтенатива частично нерабочему toPlaceholder.
  • Тип поля "Список ресурсов" (resourcelist) с ограничением по родителю (parents)
  • Простая и симпатичная галерея fancybox

Что такое MIGX?

MIGX это специальный тип дополнительных полей (TV), созданный для того чтобы объединить несколько разных TV в один. Такая система объединенных полей очень сильно упрощает администрирование сайта, когда есть необходимость заполнять много информации. Поля ввода в MIGX могут быть всеми стандартными типами - Текст, цифра, выпадающий список, картинка, чекбокс и пр.

Пакет позволяет разработчику гибко настроить структуру и набор используемых полей ввода в рамках одного MIGX-поля.

Дополнение поставляется со снипппетом getImageList, который позволяет быстро и просто вывести данные из заполненного дополнительного поля MIGX

MIGX расшифровывается как MultiItemsGridtv for MODX

Как работает специльный тип дополнительных полей (TV) MIGX

MIGX позволяет хранить сложную структуру данных в едином TV-поле. Данные хранятся в формате JSON. Данная документация предполагает, что вы имеете представление о том, что такое JSON.

Создание первого TV MIGX

Заготовка для конфигурации MIGX находится в директории /core/components/MIGX/examples/. В нижеследующем примере мы будем использовать заготовку "tabs.txt". Эта документация предполагает, что у вас установленно дополнение TinyMCE.

Файл tabs.txt содержит пример реализации простой галереи изображений. Галерея будет состоять из единого элемента, который объединяет в себе одно текстовое поле с редактором (описание изображения), одно поле изображения (само изображение), и короткую строку (заголовок). Все эти данные будут храниться в одном TV-поле.

Шаг 1: Создайте TV MIGX

• Заполните название, заголовок и все остальное как у любого другого TV-поля.
• Укажите к какому шаблону относится TV-поле
• Укажите тип ввода - MIGX

Шаг 2: Настроить поля ввода MIGX
Шаг 2.1: Вкладки формы

Вкладки формы определяет какие поля ввода будут предоставлены пользователю.

Скопируйте содержимое tabs.txt в поле "Вкладки формы"

[
{
    "caption":"Info",
    "fields": [
        {
            "field":"title",
            "caption":"Title"
        },
        {
            "field":"description",
            "caption":"Description",
            "inputTVtype":"richtext"
        }
    ]
},
{
    "caption":"Image",
    "fields":[
        {
            "field":"image",
            "caption":"Image",
            "inputTVtype":"image",
            "sourceFrom":"MIGX"
        }
    ]
}
] 

Сейчас мы разберем этот JSON на составляющие чтобы понять что есть что.

• Первый ключ "caption" отвечает за то какой заголовок будет у вкладки. В данном случае - "Info".
• Второй ключ "fields" Содержит информаци о полях, доступных для редактирования в этой вкладке.
  • Первый ключ элемента fields - "field". Значение этого ключа соотвествует имени плейсхолдера при выводе данных через getImageList.
  • Второй ключ элемента fields - "caption". Это заголовок, который увидит пользователь, заполняющий данные в панели управления.
  • Третий ключ элемента fields - "inputTVtype". Позволяет указать тип TV (ДАТЬ СПИСОК)(по-умолчанию "text")
• • Во второй вкладке мы указали "inputTVtype":"image" для того чтобы можно было загружать изображения.
  • "sourceFrom":"MIGX" - если нужно чтобы изображения брались из предустановленного в настройках TV-поля источника файлов.

Ключи для "Вкладки форм"

Шаг 2.2: Разметка колонок

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

Скопируйте содержимое columns.txt в поле "Разметка колонок"

[
{"header": "Title", "width": "160", "sortable": "true", "dataIndex": "title"},
{"header": "Image", "width": "50", "sortable": "false", "dataIndex": "image","renderer": "this.renderImage"}
]

Ключи для "Разметки колонок"

Ввод данных

Шаг 1: Установка

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

Шаг 2: Ввод данных

1. Зайдите в ваш ресурс, а затем перейдите на вкладку "Дополнительные поля". Вы должны увидеть новое дополнительное поле.
2. Нажмите на кнопку "Добавить"
   Заполните поля, которые вы определили в настройках дополнительного поля. Если вы не видите никаких полей, убедитесь, что заполнили поле "Вкладки формы" соблюдая синтаксис JSON (Иногда при копировании примеров вы можете вставить неразрывные пробелы вместо обычных, в таком случае JSON не будет валидным)
3. Нажмите кнопку "Готово"
4. Нажмите кнопку "Сохранить", чтобы сохранить ресурс

Шаг 3: Изменение данных

Щелкните правой кнопкой мыши на любом элементе. Выберите либо Update, дублировать или удалить.

Шаг 4: Упорядочивание данных

Зажмите и перетащите элемент, чтобы изменить его положение в таблице.

Вывод данных через getImageList

Отображение элементов MIGX

В комплекте с пакетом MIGX поставляется сниппет getImageList, который подходит для вывода данных из заполненного TV MIGX. Не смотря на название он может быть использован не только для вывода изображений, но для всех типов данных. Это что-то вроде getResources, но специально для MIGX.

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

• галерея изображений
• слайдер с картинками или HTML
• табличные данные
• CSV или XML
• Что угодно на самом деле

Пример использования getImageList

Давайте выведем изображения, которыми мы заполнили TV MIGX на шаге 2. Вставьте этот код там, где вы хотите увидеть картинки.

  [[getImageList? 
    &tvname=`myMIGXtv`
    &tpl=`@CODE:<li>[[+idx]]<img src="[[+image]]"/><p>[[+title]]</p></li>
  `]]

tvname - название TV-поля. tpl - шаблон вывода. В tpl вы можете указать как название чанка, так и строку кода. Убедитесь, что указали @CODE:, если решили использовать указать шаблон строчно. При использовании чанка достаточно указать только название этого чанка.

Вывод с использованием RezImgCrop:

<li>
  <img src="[[+image:rezimgcrop=`r-250`]]" alt="[[+title]]"/>
</li>

Вывод MIGX TV внутри шаблона getResources

<li>
  <a href="[[~[[+id]]]]">[[+pagetitle]]</a>  
  [[getImageList?
    &tvname=`myMIGXtv`
    &tpl=`thumbTpl`
    &limit=`1`
    &docid=`[[+id]]`
  ]]
</li>

Использование переменных из getResources в getImageList

Если вы хотите использовать переменные, поставляемые в шаблон getResources внутри шаблона getImageList вы можете передать эти данные в параметрах вызова getImageList. Вы можете задать произвольные имена этим параметрам, а вызывать их с помощью конструкции [[+property.myparam1]] в шаблоне getImageList.

[[getImageList?
    &tvname=`myMIGXtv`
    &tpl=`thumbTpl2`
    &docid=`[[+id]]`
    &limit=`1`
    &pagetitle=`[[+pagetitle]]`
    &originalResourceId=`[[+id]]`
]]

<li>
    <a href="[[~[[+property.originalResourceId]]]]">Показать еще изображения от [[+property.pagetitle]]</a>
</li>

Параметры сниппета getImageList

Доступные плейсхолдеры в шаблоне вывода getImageList

Продвинутое использование

Динамическая замена шаблона

Используя &tpl=`@FIELD:` можно установить любое поле шаблоном для вывода.

[[getImageList?
 &tvname=`myMIGXtv`
 &tpl=`@FIELD:mytplfield`
]]

Если вы определили поле "mytplfield" в настройках MIGX TV, getImageList будет использовать значение этого поля как шаблон для вывода данного элемента. Шаблон внутри поле "mytplfield" должен быть точно таким же, как содержание чанка, используемого обычно в &tpl=`chankname`.