Мы представляем новый type: objects среди поддерживаемых типов для настроек темы, который может заменить существующий тип json_schema, который мы планируем скоро вывести из эксплуатации.
Определение настройки темы типа objects
Чтобы создать настройку темы типа objects, сначала определите ключ верхнего уровня, так же как и любую другую настройку темы, который будет использоваться как имя настройки.
links: ...
Затем добавьте ключевые слова type, default и schema к настройке.
links:
type: objects
default: []
schema: ...
type: objects указывает, что это будет настройка типа objects, а аннотация default: [] устанавливает значение настройки по умолчанию как пустой массив. Обратите внимание, что значение по умолчанию также может быть установлено как массив объектов, что мы продемонстрируем после определения schema.
Чтобы определить схему, сначала определите name схемы следующим образом:
links:
type: objects
default: []
schema:
name: link
Далее мы добавим ключевое слово properties к схеме, которое позволит нам определять и валидировать структуру каждого объекта.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
В примере выше мы указываем, что объект link имеет свойство name. Чтобы определить ожидаемый тип данных, каждое свойство должно определять ключевое слово type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
Приведенное выше определение схемы указывает, что объект link имеет свойство name типа string, что означает, что для этого свойства будут приняты только строковые значения. В настоящее время поддерживаются следующие типы:
-
string: Значение свойства сохраняется как строка. Установитеtextarea: true, чтобы использовать расширяемую текстовую область:description: type: string textarea: true validations: max_length: 500 -
integer: Значение свойства сохраняется как целое число. -
float: Значение свойства сохраняется как число с плавающей точкой. -
boolean: Значение свойства —trueилиfalse. -
upload: Значение свойства — URL вложения. -
enum: Значение свойства должно быть одним из значений, определенных в ключевом словеchoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: Значение свойства — массив корректных ID категорий. -
groups: Значение свойства — массив корректных ID групп. -
tags: Значение свойства — массив корректных имен тегов. -
icon: Значение свойства — имя одной иконки из набора иконок Discourse. Выбранные иконки автоматически добавляются в спрайт-шиту, поэтому они могут отображаться без отдельной регистрации.
При обновлении настройки темы типа objects через API массивы tags могут содержать исходные имена тегов, целочисленные ID тегов или и то, и другое. ID разрешаются в исходные имена перед валидацией и сохранением. Темы по-прежнему получают массивы исходных имен. Числовые строки трактуются как имена, а не ID, и значения по умолчанию должны использовать имена.
Стандартный фронтенд-рендер тегов включает data-tag-id для объектов тегов с ID или для имен тегов, отрисованных с опцией tagId. Существующий атрибут data-tag-name остается неизменным. ID остается тем же во всех локалях, даже если отображаемое имя меняется. Вызовы рендеринга только по имени без ID пропускают data-tag-id.
Объекты с непосредственными свойствами tags автоматически получают сопутствующий массив tag_objects в настройках фронтенда:
{
tags: ["support"],
tag_objects: [
{ id: 42, name: "support" }
]
}
Существующие массивы имен тегов остаются неизменными. Каждый сопутствующий объект содержит ID тега и точную исходную строку имени из настройки, включая регистр. Он не подставляет переведенное отображаемое имя. Компоненты могут использовать ID для ссылки на выбранные теги, например, при таргетировании data-tag-id в CSS. Ядро не отображает сопутствующий массив в интерфейсе и не добавляет административную настройку для него.
Сопутствующий массив объединяет непосредственные выбора tags объекта в их исходном порядке, сохраняя повторяющиеся выборы. Вложенные объекты получают свои собственные сопутствующие массивы. Включаются только теги, видимые посетителю; отсутствующие, удаленные или скрытые выборы исключаются. Сопутствующий массив присутствует как [], когда ни один тег не разрешен. Не предполагайте, что его индексы совпадают с исходным строковым массивом.
Не требуется opt-in или дополнительных запросов к браузерному API. Свойство схемы, определенное автором под именем tag_objects, имеет приоритет: ядро сохраняет это поле и не генерирует сопутствующий массив на этом уровне. Объявите любое существующее пользовательское поле с этим именем; необъявленные значения tag_objects трактуются как сгенерированные метаданные и удаляются. Объекты без непосредственных свойств tags и устаревшие настройки списков тегов верхнего уровня остаются неизменными.
Сопутствующий массив генерируется только для данных страницы фронтенда. Сохраненные настройки и значения редактирования в админке сохраняют свою существующую структуру; сгенерированные метаданные, отправленные обратно через API настроек, отбрасываются. Компоненты, поддерживающие контексты или старые версии Discourse без этих данных, могут проверять Array.isArray(style.tag_objects) и возвращаться к существующему поведению на основе имен, если оно недоступно.
После определения схемы значение настройки по умолчанию теперь можно задать, определив массив в yaml следующим образом:
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
Обязательные свойства
Все определенные свойства по умолчанию являются необязательными. Чтобы пометить свойство как обязательное, просто аннотируйте свойство required: true. Свойство также может быть помечено как необязательное аннотацией required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Пустые значения string, datetime и icon, а также пустые списки categories, groups и tags считаются отсутствующими: обязательные свойства отклоняют их, а необязательные свойства пропускают их валидации. false считается установленным.
Пользовательские валидации
Для некоторых типов свойств существует встроенная поддержка пользовательских валидаций, которые можно объявить, аннотируя свойство ключевым словом validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Валидации для типов string
min_length: Минимальная длина свойства. Значение ключевого слова должно быть целым числом.max_length: Максимальная длина свойства. Значение ключевого слова должно быть целым числом.url: Проверяет, что свойство является корректным URL. Значение ключевого слова может бытьtrue/false.
Валидации для типов integer и float
min: Минимальное значение свойства. Значение ключевого слова должно быть целым числом.max: Максимальное значение свойства. Значение ключевого слова должно быть целым числом.
Валидации для типов tags, groups и categories
min: Минимальное количество записей для свойства. Значение ключевого слова должно быть целым числом.max: Максимальное количество записей для свойства. Значение ключевого слова должно быть целым числом.
Разрешение членства в группах
Настройки объектов могут разрешать свойства type: groups в булево значение для текущего пользователя. Это полезно, когда код темы должен знать только, входит ли текущий пользователь в одну из настроенных групп, поскольку currentUser.groups включает только группы, видимые пользователю.
Добавьте resolve_group_membership: true к свойству groups:
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
Интерфейс администратора и сохраненное значение настройки по-прежнему используют исходный массив groups. В объекте settings среды выполнения фронтенда Discourse удаляет ID групп из каждого объекта и добавляет булево значение с тем же именем свойства, префиксом user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// Пользователь состоит как минимум в одной выбранной группе для этого раздела.
}
}
Эта опция действительна только для свойств схемы объекта с type: groups. Она также работает с вложенными схемами объектов и с автоматическими группами, такими как logged_in_users и anonymous_users.
Структура вложенных объектов
Объект также может иметь свойство, содержащее массив объектов. Чтобы создать структуру вложенных объектов, свойство также можно аннотировать type: objects и соответствующим определением schema.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
Описание и локализация настроек
Чтобы добавить описание для настройки в локали en, создайте файл locales/en.yml со следующим форматом для следующей настройки темы типа objects.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: Это описание для настройки темы sections
schema:
properties:
name:
label: Имя
description: Описание для свойства
links:
name:
label: Имя
description: Описание для свойства
url:
label: URL
description: Описание для свойства
Переводимый текст объектов
Объявите обязательное строковое свойство с именем translation_key и пометьте текстовые свойства с помощью translatable: true, чтобы сделать их доступными в Текстах сайта. Ядро читает значения по умолчанию из сохраненных настроек объектов и включает их в обычные ресурсы переводов темы. Компонентам темы не требуется код на бэкенде.
links:
type: objects
default:
- translation_key: guidelines
label: Правила сообщества
schema:
name: link
identifier: label
properties:
translation_key:
type: string
required: true
label:
type: string
translatable: true
Это exposes js.theme_translations.<theme_id>.links.guidelines.label с текстом по умолчанию «Community guidelines» и языком текста по умолчанию en. Фронтенд продолжает использовать i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label }) для каждой ссылки в настройке.
Редактор предпросматривает относительные ключи для передачи в themePrefix и ссылки на Тексты сайта, отфильтрованные по компоненту. Сохраните изменения перед управлением переводами.
Ядро ограничивает ключи ID установленного темы и именем настройки объекта. Язык текста по умолчанию — en; опционально установите translations: { default_locale: fr } в корневой схеме, чтобы изменить его. В противном случае блок translations не требуется. Вложенные схемы объявляют свое собственное обязательное строковое свойство translation_key и помечают свои переводимые свойства; ключи родительских объектов и имена свойств коллекций включаются в каждый вложенный ключ. Например, раздел с ключом getting_started, содержащий ссылку с ключом guidelines, создает theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label для настройки resource_sections.
Схемы с переводимыми полями, включая их родительские схемы объектов, должны объявлять translation_key с type: string и required: true. Валидация схемы проверяет это, даже если список объектов по умолчанию пуст. Отдельная опция schema.identifier: label выбирает отображаемую метку редактора; она не выбирает идентификатор перевода.
Используйте стабильные, вручную присвоенные идентификаторы, начинающиеся со строчной буквы и содержащие только строчные буквы, цифры и подчеркивания. Идентификаторы должны быть не длиннее 80 символов и уникальны в каждой коллекции. Имена переводимых настроек, имена полей и имена вложенных коллекций также начинаются со строчной буквы и содержат только строчные буквы, цифры и подчеркивания. Изменение порядка сохраняет переводы. Переименование идентификатора создает новые ключи перевода; дублирование объекта требует другого ключа. Отдельные установки компонентов имеют независимые пространства имен.
При добавлении переводимых полей в существующий компонент предоставьте миграцию настроек, которая добавляет корректные значения translation_key в настроенные объекты. Обновления компонентов валидируют финальные ключи перевода объектов и перестраивают свои переводы после завершения миграций настроек. Некорректные финальные ключи откатывают обновление. Обычные сохранения редактора объектов валидируют немедленно. Если сохраненные идентификаторы объектов некорректны, пути чтения пропускают значения по умолчанию объектов, чтобы переводы и ресурсы файлов локалей оставались доступными; сохранение настроек объектов и применение миграций по-прежнему валидируют строго.
Участвуют только строковые поля, помеченные translatable: true. Не помеченные поля и поля с translatable: false исключаются. Пустые необязательные поля сохраняют свои ключи и существующие переводы. Очистка текста по умолчанию не удаляет переводы. Вложенные коллекции включают свое имя свойства в ключ, поэтому отдельные коллекции могут повторно использовать одни и те же идентификаторы объектов.
Значения по умолчанию включают значения по умолчанию темы и импортированные настройки. Изменение текста по умолчанию помечает переводы устаревшими. Значения по умолчанию остаются в настройке объекта; переводы используют существующую модель ThemeTranslationOverride, так же как поля файлов локалей. Отдельного реестра текста нет.
Удаление объекта, объявления переводимого поля или ключа файла локалей не удаляет его сохраненные переопределения переводов. Переопределения без текущего источника имеют статус deprecated и сохраняются при сохранении настроек, миграциях и обновлениях компонентов. Восстановление того же ключа перевода повторно использует сохраненную кастомизацию, в том числе после отката компонента. Это сохраняет существующее поведение перевода файлов локалей для компонентов, которые не используют переводы объектов. Удаленные ключи не отображаются в Текстах сайта до возвращения их исходных объявлений.
Если изменения схемы приводят к тому, что сохраненный ключ конфликтует с вложенной структурой текущего ключа, текущее объявление определяет форму среды выполнения. Оба сохраненных переопределения остаются доступными для восстановления, если схема будет откатана.
Явный возврат перевода по-прежнему удаляет это переопределение и восстанавливает поставляемое значение по умолчанию для выбранной локали. Удаление компонента удаляет все его переопределения переводов.
Тексты сайта показывают текст по умолчанию и его язык рядом с редактируемым переводом. И поля редактора объектов, и строки, поставляемые в файлах локалей, используют js.theme_translations.<theme_id>.<key> в Текстах сайта. Переводы, сохраненные до появления отслеживания значений по умолчанию, имеют неизвестную базовую линию и исключаются из фильтра устаревших. Подтверждение текущего значения по умолчанию устанавливает базовую линию без изменения перевода. Плейсхолдеры интерполяции полей объектов проверяются по объявленному исходному тексту, а не по пользовательским переопределениям источника. Формы множественного числа могут использовать плейсхолдеры, объявленные их однофамильной формой other. Переопределения файлов локалей сохраняют свое существующее неограниченное поведение плейсхолдеров, потому что компонент может предоставлять аргументы среды выполнения, которые не используются в поставляемом тексте. Тексты сайта не помечают эти аргументы как некорректные.
Отслеживание значений по умолчанию использует сохраненное поле объекта или поставляемый английский текст, падая на поставляемый текст выбранной локали, если ключ на английском языке отсутствует. Переопределения исходной локали не заменяют эту базовую линию. Язык значения по умолчанию показывается явно; возврат переопределения файла локалей по-прежнему восстанавливает текст, поставляемый для выбранной локали.
Имя настройки резервирует пространство имен в пределах темы. Файл локалей не может также определить корневой ключ этой настройки: сохранение настройки объекта или обновление темы отклоняет конфликт. Текст доставляется через существующие кэшированные ресурсы переводов темы только для активной темы и ее компонентов, включая предпросмотры.
Этот документ находится под контролем версий — предложите изменения на github.



