Тип объектов для настройки темы

Мы представляем новый 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.

16 лайков

Мне всё ещё не очевидно, что отказ от стиля JSON Schema — это хорошая идея.

Хотя эти схемы могут становиться довольно сложными и не являются самым «дружелюбным к разработчикам» форматом (так что в этом плане это отличное изменение), существуют онлайн-инструменты для валидации JSON Schema, что является действительно полезным способом проверки как самой схемы, так и любых данных по умолчанию.

Например: https://www.jsonschemavalidator.net/

Как это будет работать в новом мире?

2 лайка

При загрузке темы мы будем проверять данные по умолчанию на соответствие определённой схеме. Тем не менее, в настоящее время мы не проверяем валидность самой схемы, хотя это не составило бы для нас большого труда. Даже для настройки JSON Schema сейчас, я не думаю, что мы проверяем данные по умолчанию на соответствие определённой схеме.

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

2 лайка

Здесь есть несколько крутых функций:

  • Вы можете отказаться от JSON.parse и получать доступ к настройке напрямую к объекту get, что очень удобно.

  • Валидатор URL!

:chefs_kiss: :chefs_kiss:

5 лайков

Есть ли способ, чтобы в редакторе учитывались несколько строк?

Это по умолчанию работает:

- name: markdown
  value: > 
    ## Заголовок
      * первый пункт
      * второй пункт

Но как только вы отредактируете это, переносы строк теряются.

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

5 лайков

Вот несколько замечаний:

2 лайка

Я заметил это, и проблема была исправлена в

1 лайк

Будет ли у нас возможность менять порядок элементов в интерфейсе?

Например, это редактор настроек объекта в компоненте темы «Лёгкий подвал». Сейчас я не могу переставить ни один элемент:

4 лайка

Я тоже хотел бы предложить эту функцию! :+1:


Кстати, было бы полезно, если бы в первом сообщении содержалась информация о свойстве identifier.

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

4 лайка

Изменение порядка элементов определённо также обсуждалось внутри команды. Я постараюсь внедрить это на этой неделе.

Принято. Я обновлю первое сообщение, добавив информацию о свойстве identifier.

5 лайков

Да, чтобы заменить (скоро устаревающую?) систему JSON, она должна соответствовать или превосходить старый интерфейс:

включая порядок элементов.

1 лайк

Привет! Планируется ли в ближайшее время поддержка других типов полей?

Например:

  • long_string с форматированием Markdown; возможно, с настраиваемой панелью инструментов,
  • поле date (с правилами валидации),
  • поле color (с правилами валидации)?
1 лайк

В настоящее время таких планов нет, хотя я согласен, что это было бы полезно. Мне самому хотелось бы иметь поле icon.

8 лайков

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

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

links:
  type: objects
  default:
    - name: link 1
      title: link 1 title
    - name: link 2
      title: link 2 title
  schema:
    name: link
    properties:
      is_active:
        type: boolean
        default: true 

default: true здесь не будет работать, как ожидалось.

Возможно ли установить значения по умолчанию для каждого поля для всех создаваемых записей?

Можно ли импортировать свойства объекта в переменные в Sass?

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

1 лайк

Спасибо, что поделились примером! Хотя да… это выглядит не очень заманчиво :upside_down_face:

1 лайк

Из любопытства, не тратя много времени на изучение, как обстоят дела с этим?

2 лайка

Да, это не очень хорошо, не делайте так. :smile:. Это была скорее попытка проверить, возможно ли это, но не разумный подход. Я согласен с вами; было бы здорово иметь прямой способ! :+1:

Я тоже хотел бы это знать!
Кроме того, если я прав, это была бы единственная недостающая функция для паритета с json_schema.

2 лайка

Я искал возможность использовать тип загрузки, но её нет.
При беглом взгляде на ядро видно, что типы тема, пост и загрузка реализованы на стороне сервера, но не на фронтенде. Есть ли для этого какая-то конкретная причина? :thinking: