Работа с шаблонами

В Deneb есть несколько встроенных шаблонов, доступных в диалоге Create New Specification. Их использование показано в простом практическом примере, где мы создаём первую диаграмму.

Шаблоны не могут охватить все задачи: они помогают начать работу. Вы можете создавать собственные шаблоны или импортировать шаблоны других авторов.

Импорт шаблона

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

В диалоге Create New Specification расширенного редактора можно импортировать шаблон:

Выберите способ Existing template, затем нажмите область под Import your file, чтобы найти файл шаблона с расширением .json. Выбрав файл, нажмите Open.

Если содержимое шаблона Deneb скопировано в буфер обмена — как обычный текст или как файл из Проводника, — вставьте его в диалог сочетанием Ctrl + V. Deneb импортирует его, если распознает допустимый шаблон.

Поля-заполнители набора данных

JSON выбранного файла проходит проверку. Если она успешна, отображаются сведения о полях-заполнителях:

Рядом с именем каждого поля-заполнителя указан рекомендуемый тип данных — тот, который использовался в наборе данных автора.

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

Если автор добавил описание поля-заполнителя, его можно посмотреть с помощью значка информации рядом с ним.

Назначение полей

Откройте список поля-заполнителя и выберите подходящий столбец или меру из своего набора данных:

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

После назначения всех полей-заполнителей кнопка Create становится доступна:

Нажмите Create: шаблон будет добавлен в расширенный редактор, а поля-заполнители заменены назначенными полями:

У каждого пользователя свои данные, поэтому, вероятно, потребуются дополнительные изменения спецификации для вашей задачи. В остальном всё готово! 😄

Создание шаблона

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

В расширенном редакторе выберите команду Generate JSON Template. Откроется диалог.

Сведения о шаблоне

Укажите понятное имя шаблона и более подробное описание. Эти сведения показываются пользователям при импорте и должны помогать им назначать поля.

Добавление изображения предварительного просмотра

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

Когда вы отметите этот флажок, Deneb:

• Создаст PNG-изображение текущего представления редактора с помощью Vega View API.
• Ограничит его размер максимумом 150 × 150 пикселей, чтобы уменьшить объём шаблона.
• Сохранит соотношение сторон, ориентируясь на большую сторону изображения — ширину или высоту.
• Включит изображение в формате base64 в свойство usermeta.information.previewImageBase64PNG. Подробнее см. ниже.

Набор данных шаблона

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

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

Если оставить текстовое поле пустым или удалить его содержимое, будет использовано исходное имя из набора данных. Для сравнения оно также показано в столбце Original field.

Для каждого поля предусмотрено необязательное поле Author's notes. В него можно добавить пояснения для пользователей. Описание будет показано рядом с полем-заполнителем при импорте.

Проверка и экспорт

Когда всё готово, скачайте файл шаблона или скопируйте его в буфер обмена. Во втором случае вставьте содержимое в удобный редактор и сохраните файл с расширением .json.

Структура шаблона

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

Шаблон — это спецификация Vega или Vega-Lite с дополнительным объектом usermeta (Vega | Vega-Lite). Обычный внешний парсер Vega игнорирует этот объект, но Deneb использует его для проверки шаблона. Он включает следующие объекты.

deneb

Все свойства обязательны.

• build — версия Deneb, в которой создан шаблон.
  • Свойство обязательно, но на этом этапе используется только для диагностики. Лучше оставить его без изменений.
• metaVersion — версия метаданных шаблона.
  • Допустимые значения: 1 (метаданные v1) и 2 (метаданные v2). Новые шаблоны всегда создаются со значением 2; 1 сохраняется только для совместимости с шаблонами, созданными до Deneb 2.0.
  • Значение указывает версию схемы шаблона и определяет преобразования при импорте старого шаблона.
  • Например, при импорте шаблона v1 в Deneb, ожидающий метаданные v2, структура автоматически приводится к текущему формату.
• provider — поставщик, используемый при загрузке и разборе шаблона.
  • Допустимые значения: vega и vegaLite.
  • Если изменить свойство вручную, Deneb попытается определить поставщика по $schema верхнего уровня, если оно задано, а затем — по самой спецификации. Успех не гарантирован.

information

Следующие обязательные свойства заполняются по сведениям автора на панели Template Information диалога Create JSON Template:

• name — имя шаблона, показываемое пользователю в диалоге после импорта.
• description — подробное описание назначения шаблона, показываемое после импорта.
• author — сведения об авторе.
  • Сейчас они не отображаются в диалоге импорта, но это может измениться.

Следующие обязательные свойства создаёт сам Deneb:

• uuid — уникальный идентификатор шаблона.
• generated — время создания шаблона в UTC.

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

• supportUri — URI дополнительных сведений о шаблоне, например блога или сайта.
• videoUri — URI вспомогательного видео, например демонстрации или инструкции.
• previewImageBase64PNG — PNG-изображение в формате base64 для миниатюры или вспомогательной иллюстрации.
  • Если оно включено в шаблон, показывается в диалоге Create New Specification.
  • Размер изображения не должен превышать 150 × 150 пикселей.

В объект information можно добавлять любые свойства для собственных нужд. Deneb игнорирует их при импорте.

datasets

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

Во время выполнения Deneb считает, что у каждого шаблона один набор данных по умолчанию с именем dataset. Поэтому обычно объект содержит один ключ:

{
  "datasets": {
    "dataset": [
      { "key": "__dataset.0__", ... },
      { "key": "__dataset.1__", ... }
    ]
  }
}

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

Каждое поле-заполнитель имеет следующие свойства:

interactivity

Необязательный объект настроек интерактивности, применяемых при импорте шаблона. Если он отсутствует, используются значения Deneb по умолчанию.

config

Необязательная строка с содержимым редактора конфигурации: JSON или JSONC, преобразованный в строку, как на панели Config Editor. Если свойство отсутствует, предполагается пустая конфигурация {}.

Дополнительные сведения для разработчиков

Если вы создаёте шаблоны вне Deneb для последующего импорта, убедитесь, что их основная спецификация соответствует требованиям Vega или Vega-Lite.

Объект usermeta расширяемый. Для проверки того, что Deneb правильно разберёт его при импорте, доступны JSON-схемы:

• Текущая (v2): deneb-template-usermeta-v2.json.
• Прежняя (v1): deneb-template-usermeta-v1.json. Сохранена для проверки шаблонов до версии 2.0 перед импортом и преобразованием.