Главная страница>Связанные с программированием>Другой исходный код
Скачать

Копенгагенская тема от Zendesk

Тема «Копенгаген» является темой Zendesk Guide по умолчанию. Он спроектирован так, чтобы быть отзывчивым и доступным. Узнайте больше о настройке Zendesk Guide здесь.

Тема «Копенгаген» для Справочного центра состоит из:

  • Файл манифеста
  • Набор шаблонов
  • Таблица стилей и файлы JavaScript
  • Папка активов.

Как использовать

Это последняя версия темы Копенгаген, доступная для Guide. Этот репозиторий можно использовать в качестве отправной точки для создания собственной темы. Вы можете разветвить этот репозиторий по своему усмотрению. Вы можете использовать свою любимую среду IDE для разработки тем и предварительного просмотра изменений локально в веб-браузере с помощью ZCLI. Подробности читайте в документации по темам zcli.

Настройка вашей темы

После того как вы разветвите этот репозиторий, вы сможете свободно редактировать шаблоны, CSS, JavaScript и управлять ресурсами.

Файл манифеста

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

Папка настроек

Если у вас есть переменная типа file , вам необходимо предоставить файл по умолчанию для этой переменной в папке /settings . Этот файл будет использоваться на панели настроек по умолчанию, и пользователи могут при желании загрузить другой файл. Бывший. Если вы хотите иметь переменную для фонового изображения раздела, переменная в вашем файле манифеста будет выглядеть примерно так: 

 {
  ...
  "settings" : [ {
    "label" : "Images" ,
    "variables" : [ {
      "identifier" : "background_image" ,
      "type" : "file" ,
      "description" : "Background image for X section" ,
      "label" : "Background image" ,
    } ]
  } ]
}

И это будет искать файл в папке настроек с именем: background_image

Добавление активов

Вы можете добавлять ресурсы в папку ресурсов и использовать их в CSS, JavaScript и шаблонах. Подробнее об активах можно прочитать здесь

Публикация вашей темы

После настройки темы вы можете загрузить репозиторий в виде zip файла и импортировать его в Theming Center.

Вы можете следить за документацией по импорту здесь.

Вы также можете импортировать напрямую из GitHub — подробнее здесь.

Шаблоны

Тема включает в себя все шаблоны, используемые для Справочного центра со всеми доступными функциями. Список шаблонов в теме:

  • Страница статьи
  • Страница категории
  • Страница со списком сообщений сообщества
  • Страница публикации в сообществе
  • Страница со списком тем сообщества
  • Страница темы сообщества
  • Страница вкладов
  • Глава документа
  • Страница ошибки
  • Нижний колонтитул
  • Заголовок
  • Домашняя страница
  • Новая страница публикации в сообществе
  • Новая страница запроса
  • Страница запросов
  • Страница результатов поиска
  • Страница раздела
  • Страница подписок
  • Страница профиля пользователя

Вы можете добавить до 10 дополнительных шаблонов для:

  • Страница статьи
  • Страница категории
  • Страница раздела

Вы делаете это, создавая файлы в папках templates/article_pages , templates/category_pages или templates/section_pages . Узнайте больше здесь.

Таблица стилей и JavaScript

Мы используем Rollup для компиляции файлов JS и CSS, которые используются в теме — style.css и script.js . Не редактируйте их напрямую, поскольку они будут созданы повторно во время выпуска.

Чтобы начать: 

$ yarn install
$ yarn start

Это скомпилирует весь исходный код в src и styles и будет отслеживать изменения. Также начнется preview .

Примечания:

  • Мы намеренно не используем Babel при компиляции script.js , чтобы получить чистый результат сборки. Обязательно используйте только широко поддерживаемые функции ecmascript (ES2015).
  • Не редактируйте style.css , script.js и файлы внутри папки assets напрямую. Они регенерируются во время выпуска.
  • Для предварительного просмотра требуется вход в систему, поэтому обязательно сначала запустите yarn zcli login -i если вы не сделали этого раньше.

Ресурсы

Тема «Копенгаген» включает в себя несколько ресурсов JavaScript, но вы можете добавить в тему другие ресурсы, поместив их в папку assets .

Компоненты реагирования

Начиная с версии 4.0.0, тема Copenhagen использует некоторые компоненты React для рендеринга частей пользовательского интерфейса. Эти компоненты расположены в папке src/modules и созданы с использованием библиотеки компонентов Zendesk Garden.

Эти компоненты входят в состав собственных модулей JavaScript как часть процесса сборки накопительного пакета и создаются в виде файлов JS в папке assets . Поскольку ресурсы переименовываются при установке темы, модули необходимо импортировать с помощью помощника по ресурсам.

Чтобы упростить процесс импорта модулей, мы добавили плагин Rollup, который генерирует карту импорта, сопоставляющую имя модуля с URL-адресом ресурса. Эта карта импорта затем вводится в шаблон document_head.hbs во время сборки.

Например, если вы определили модуль с именем my-module в папке src/modules/my-module , вы можете добавить его в rollup.config.mjs следующим образом: 

 export default defineConfig ( [
  // ...
  // Configuration for bundling modules in the src/modules directory
  {
    // ...
    input : {
      "my-module" : "src/modules/my-module/index.js" ,
    } ,
    // ...
  }
] ) ;

В результате накопительного пакета в папке assets будет создан файл с именем my-module-bundle.js , и эта карта импорта будет добавлена ​​в шаблон document_head.hbs : 

 < script type =" importmap " >
{
  "imports" : {
    "my-module" : "{{asset 'my-module-bundle.js'}}" ,
  }
}
</ script >

Затем вы можете импортировать модуль в свои шаблоны следующим образом: 

 < script type = " module " >
  import { something } from " my-module " ;

  // ...
</ script >

Интернационализация

I18n реализован в компонентах React с использованием библиотеки act-i18next. Мы используем простой файл JSON и используем расширение . в качестве разделителя для множественного числа, который отличается от значения по умолчанию _ и настраивается во время инициализации.

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

Интеграция с системой перевода Zendesk

Добавление строк перевода

Строки перевода добавляются непосредственно в исходный код, обычно с использованием хука useTranslation , передавая ключ и значение английского языка по умолчанию: 

 import { useTranslation } from 'react-i18next' ;

function MyComponent ( ) {
  const { t } = useTranslation ( ) ;

  return < div > { t ( "my-key" , "My default value" ) } < / div>
}

Предоставление английского значения по умолчанию в коде позволяет использовать его в качестве резервного значения, когда строки еще не переведены, и извлекать строки из исходного кода в файл YAML переводов.

Множественное число

При использовании множественного числа нам необходимо предоставить значения по умолчанию для zero , one и other значений, как того требует наша система перевода. Это можно сделать, передав значения по умолчанию в параметрах функции t . 

 t ( "my-key" , {
  "defaultValue.zero" : "{{count}} items" ,
  "defaultValue.one" : "{{count}} item" ,
  "defaultValue.other" : "{{count}} items" ,
  count : ...
} )

Извлечение строк

Сценарий bin/extract-strings.mjs можно использовать для извлечения строк перевода из исходного кода и помещения их в файл YAML, который подбирается нашей внутренней системой перевода. Использование сценария описано в самом сценарии.

Скрипт оборачивает инструмент i18next-parser и преобразует его выходные данные в формат YAML, используемый внутри страны. Подобный подход можно использовать в собственной теме, либо используя стандартный вывод i18next-parser в качестве источника для переводов, либо реализуя собственный преобразователь.

Обновление файлов перевода

Используйте bin/update-modules-translations.mjs , чтобы загрузить последние переводы для всех модулей. Затем все файлы объединяются в процессе сборки в один файл [MODULE]-translations-bundle.js .

При первом добавлении переводов в модуль вам необходимо добавить сопоставление между папкой модуля и именем пакета в системах переводов с переменной MODULE в скрипте. Например, если модуль находится в src/modules/my-module и имя пакета — cph-theme-my-module , вам необходимо добавить: 

 const MODULES = {
  ... ,
  "my-module" : "cph-theme-my-module"
}

Тестирование доступности

Мы используем собственный скрипт узла, который запускает маяк для автоматического тестирования доступности.

Есть два способа запуска скрипта:

  • Режим разработки — он запускает аудит доступности для предварительного просмотра локальной темы для определенной учетной записи. Для этого требуется запуск zcli themes:preview ;
  • Режим CI — он запускает аудит доступности активной темы конкретной учетной записи.

В зависимости от объема тестирования в дополнение к вышеперечисленному может потребоваться некоторое ручное тестирование. Такие инструменты, как Axe DevTools, программы чтения с экрана, например VoiceOver, средства проверки контрастности и т. д., могут помочь в таком тестировании.

Режим разработки

Чтобы запустить аудит доступности при смене темы:

  1. Начните компилировать и просматривать изменения, как обычно: 
$ yarn install
$ yarn start

  1. Создайте файл .a11yrc.json в корневой папке (см. пример);

    1. Укажите учетную запись/поддомен для предварительного просмотра темы и убедитесь, что она соответствует активному профилю zcli .
    2. Заполните username и password учетными данными администратора;
    3. Укажите, какие urls проверять (если оставить пустым, скрипт будет проверять все URL-адреса);

  2. В отдельной консоли запустите аудит доступности в режиме разработки: 

 yarn test-a11y -d

Затем аудит A11y будет выполняться в предварительной версии, начатой ​​на шаге 1 .

режим CI

Чтобы запустить аудит доступности в активной теме конкретной учетной записи, необходимо:

  1. Установите модули узлов: 
 yarn install
  1. Установите end_user_email , end_user_password , subdomain и urls в качестве переменных среды и запустите аудит доступности в режиме CI, т.е.: 
 end_user_email=<EMAIL> 
end_user_password=<PASSWORD> 
subdomain=<SUBDOMAIN> 
urls="
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests/new
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests" 
yarn test-a11y

Игнорировать список

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

Запись должна включать:

  • идентификатор аудита;
  • path в виде строки шаблона URL-адреса;
  • selector в виде строки.

Например: 

  custom: {
    ignore: {
      tabindex: [
        {
          path : "*" ,
          selector : "body > a.skip-navigation" ,
        } ,
      ] ,
      aria - allowed - attr : [
        {
          path : "/hc/:locale/profiles/:id" ,
          selector : "body > div.profile-info"
        }
      ]
    } ,
  } ,

В этом примере ошибки для tabindex аудита с body > a.skip-navigation будут отображаться как предупреждения на всех страницах ( * ). То же самое произойдет с аудитом aria-allowed-attr с body > div.profile-info , но только для страницы профиля пользователя /hc/:locale/profiles/:id .

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

Содействие

Запросы на включение приветствуются на GitHub по адресу https://github.com/zendesk/copenhagen_theme. Пожалуйста, укажите @zendesk/vikings при создании запроса на включение.

Мы используем обычные коммиты, чтобы улучшить читаемость истории проекта и автоматизировать процесс выпуска. Поэтому сообщение фиксации должно иметь следующий формат: 

 <type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  • тип: описывает категорию изменения. См. поддерживаемые типы.
  • область действия: (необязательно) описывает, на что влияет изменение.
  • Тема: небольшое описание изменения
  • тело: (необязательно) дополнительная контекстная информация об изменении.
  • нижний колонтитул: (необязательно) добавляет внешние ссылки, ссылки на проблемы и другую метаинформацию.

то есть: 

 chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors

Мы используем husky и commitlint для проверки сообщений при фиксации.

Мы используем действия Github вместе с semantic-release , чтобы выпустить новую версию темы после объединения PR. При каждом слиянии semantic-release анализирует сообщения фиксации и выводит семантическую версию версии. Затем он создает тег git, обновляет версию манифеста и генерирует соответствующий журнал изменений.

Типы коммитов

В списке ниже описаны поддерживаемые типы коммитов и их влияние на выпуск и журнал изменений.

Тип Описание Выпускать Журнал изменений
строить Изменения, влияющие на систему сборки или внешние зависимости. - -
работа по дому Другие изменения, не изменяющие исходный код. - -
ци Изменения в наших файлах конфигурации и сценариях CI. - -
документы Документация только меняется - -
подвиг Новая функция незначительный Функции
исправить Исправление ошибки пластырь Исправления ошибок
перформанс Изменение кода, улучшающее производительность пластырь Улучшения производительности
рефакторить Изменение кода, которое не исправляет ошибку и не добавляет новую функцию. - -
возвращаться Возвращает предыдущий коммит пластырь Возвращает
стиль Изменения, не влияющие на смысл кода (пробелы, форматирование, отсутствие точек с запятой и т. д.) - -
тест Добавление недостающих тестов или исправление существующих тестов - -

Критические изменения

Коммиты, добавляющие критические изменения, должны включать BREAKING CHANGE в тело или нижний колонтитул сообщения о фиксации.

то есть: 

 feat: update theme to use theming api v2

BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2

Затем будет создан основной выпуск и в журнал изменений будет добавлен раздел BREAKING CHANGES .

Отчеты об ошибках

Отчеты об ошибках необходимо отправлять через стандартные каналы поддержки Zendesk: https://www.zendesk.com/contact/.

Расширять
Дополнительная информация
Связанные приложения
Рекомендуем вам
Связанные новости Все