Мы представляем новый 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: Значение свойства хранится как строка.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 3categories: Значение свойства — это массив действительных идентификаторов категорий.groups: Значение свойства — это массив действительных идентификаторов групп.tags: Значение свойства — это массив действительных названий тегов.icon: Значение свойства — это название одной иконки из набора иконок Discourse. Выбранные иконки автоматически добавляются в спрайт-лист, поэтому их можно отобразить без отдельной регистрации.
После определения схемы значение по умолчанию для настройки теперь можно установить, определив массив в 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
Пользовательская валидация
Для определенных типов свойств существует встроенная поддержка пользовательской валидации, которую можно объявить, аннотируя свойство ключевым словом validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min: 1
max: 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 удаляет идентификаторы групп из каждого объекта и добавляет булево значение с тем же именем свойства, префиксированным 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: This is a description for the sections theme setting
schema:
properties:
name:
label: Name
description: The description for the property
links:
name:
label: Name
description: The description for the property
url:
label: URL
description: The description for the property
Этот документ контролируется по версиям - предложите изменения на github.
. Это была скорее попытка проверить, возможно ли это, но не разумный подход. Я согласен с вами; было бы здорово иметь прямой способ! 