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

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

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

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

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

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

Перейдите к Select JSON Template или нажмите эту кнопку, найдите файл шаблона .json и нажмите Open.

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

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

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

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

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

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

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

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

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

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

Данные у всех разные, поэтому, скорее всего, понадобится ещё немного изменить спецификацию под свою задачу. Но в остальном всё готово! 😄

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

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

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

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

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

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

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

Если установить этот флажок, Deneb выполнит следующие действия:

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

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

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

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

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

У каждого поля есть необязательное описание. При необходимости добавьте в него сведения для пользователей. При импорте это описание отображается в информационном блоке рядом с полем-заполнителем.

Проверка и копирование в буфер обмена

На последней вкладке показан JSON создаваемого шаблона, включая метаданные Deneb:

Изменить данные в этом поле нельзя. Если нужно исправить шаблон, внесите изменения в соответствующем месте:

• Спецификацию и конфигурацию изменяйте в основных редакторах.
• Для изменения полей-заполнителей вернитесь на соответствующую вкладку и исправьте сведения.

Когда всё готово, нажмите Copy справа в диалоге либо выделите текст шаблона вручную и скопируйте его сочетанием Ctrl + C.

Сохранение файла шаблона

Вставьте шаблон в удобный редактор и сохраните файл с расширением .json.

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

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

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

deneb

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

• build — версия Deneb, в которой создан шаблон.
  • Пока это свойство нужно только для диагностики проблем, хотя оно и обязательно. Поэтому лучше оставить его без изменений.
• metaVersion — версия метаданных шаблона.
  • В настоящее время поддерживается только значение 1.
• 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 их игнорирует.

dataset

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

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

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

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

deneb-template-usermeta-v1.json