Мы представляем новый 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: Значение свойства — массив допустимых идентификаторов категорий. -
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
Пустые значения для 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 удаляет идентификаторы групп из каждого объекта и добавляет логическое значение с тем же именем свойства, но с префиксом 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: Описание свойства
Этот документ имеет контроль версий — предложите изменения на github.
. Это была скорее попытка проверить, возможно ли это, но не разумный подход. Я согласен с вами; было бы здорово иметь прямой способ! 