copenhagen_theme
v4.2.3
El tema Copenhague es el tema predeterminado de Zendesk Guide. Está diseñado para ser responsivo y accesible. Obtenga más información sobre cómo personalizar Zendesk Guide aquí.
El tema de Copenhague para el Centro de ayuda consta de:
Esta es la última versión del tema Copenhague disponible para Guide. Es posible utilizar este repositorio como punto de partida para crear su propio tema personalizado. Puede bifurcar este repositorio como mejor le parezca. Puede utilizar su IDE favorito para desarrollar temas y obtener una vista previa de sus cambios localmente en un navegador web utilizando ZCLI. Para obtener más información, lea la documentación de temas de zcli.
Una vez que haya bifurcado este repositorio, podrá editar plantillas, CSS, JavaScript y administrar activos.
El manifiesto le permite definir un grupo de configuraciones para su tema que luego se pueden cambiar a través de la interfaz de usuario en Theming Center. Puede leer más sobre el archivo de manifiesto aquí.
Si tiene una variable de tipo file , debe proporcionar un archivo predeterminado para esa variable en la carpeta /settings . Este archivo se utilizará en el panel de configuración de forma predeterminada y los usuarios pueden cargar un archivo diferente si lo desean. Ex. Si desea tener una variable para la imagen de fondo de una sección, la variable en su archivo de manifiesto se vería así:
{
...
"settings" : [ {
"label" : "Images" ,
"variables" : [ {
"identifier" : "background_image" ,
"type" : "file" ,
"description" : "Background image for X section" ,
"label" : "Background image" ,
} ]
} ]
} Y esto buscaría un archivo dentro de la carpeta de configuración llamado: background_image
Puede agregar recursos a la carpeta de activos y usarlos en su CSS, JavaScript y plantillas. Puedes leer más sobre los activos aquí.
Una vez que haya personalizado su tema, puede descargar el repositorio como un archivo zip e importarlo al Theming Center.
Puede seguir la documentación para importar aquí.
También puedes importar directamente desde GitHub; obtén más información aquí.
El tema incluye todas las plantillas que se utilizan para un Centro de ayuda que tiene todas las funciones disponibles. Lista de plantillas en el tema:
Puede agregar hasta 10 plantillas opcionales para:
Para ello, cree archivos en las carpetas templates/article_pages , templates/category_pages o templates/section_pages . Obtenga más información aquí.
Usamos Rollup para compilar los archivos JS y CSS que se usan en el tema: style.css y script.js . No los edite directamente ya que se regenerarán durante el lanzamiento.
Para empezar:
$ yarn install
$ yarn start Esto compilará todo el código fuente en src y styles y observará los cambios. También comenzará preview .
Notas:
script.js para poder obtener un resultado de paquete limpio. Asegúrese de utilizar únicamente funciones de ecmascript ampliamente compatibles (ES2015).style.css , script.js ni los archivos dentro de la carpeta assets directamente. Se regeneran durante la liberación.yarn zcli login -i si no lo ha hecho antes. El tema Copenhague viene con algunos recursos de JavaScript, pero puedes agregar otros recursos a tu tema colocándolos en la carpeta de assets .
Desde la versión 4.0.0, el tema Copenhague utiliza algunos componentes de React para representar partes de la interfaz de usuario. Estos componentes se encuentran en la carpeta src/modules y se crean utilizando la biblioteca de componentes de Zendesk Garden.
Estos componentes se incluyen como módulos JavaScript nativos como parte del proceso de compilación del paquete acumulativo y se emiten como archivos JS en la carpeta de assets . Dado que los recursos cambian de nombre cuando se instala un tema, los módulos deben importarse utilizando el asistente de activos.
Para facilitar el proceso de importación de módulos, agregamos un complemento acumulativo que genera un mapa de importación que asigna el nombre del módulo a la URL del activo. Este mapa de importación luego se inyecta en la plantilla document_head.hbs durante la compilación.
Por ejemplo, si definiste un módulo llamado my-module en la carpeta src/modules/my-module , puedes agregarlo al archivo rollup.config.mjs de esta manera:
export default defineConfig ( [
// ...
// Configuration for bundling modules in the src/modules directory
{
// ...
input : {
"my-module" : "src/modules/my-module/index.js" ,
} ,
// ...
}
] ) ; El paquete acumulativo generará un archivo llamado my-module-bundle.js en la carpeta assets y este mapa de importación se agregará a la plantilla document_head.hbs :
< script type =" importmap " >
{
"imports" : {
"my-module" : "{{asset 'my-module-bundle.js'}}" ,
}
}
</ script >Luego puede importar el módulo en sus plantillas de esta manera:
I18n se implementa en los componentes de React utilizando la biblioteca react-i18next. Usamos un archivo JSON plano y usamos . como separador de plurales, que es diferente del predeterminado _ y se configura durante la inicialización.
También agregamos algunas herramientas para poder integrar la biblioteca con el sistema de traducción interno que se utiliza en Zendesk. Si está creando un tema personalizado y desea proporcionar sus propias traducciones, puede consultar la documentación de la biblioteca para configurar la carga de sus traducciones.
Las cadenas de traducción se agregan directamente en el código fuente, generalmente usando el gancho useTranslation , pasando la clave y el valor predeterminado en inglés:
import { useTranslation } from 'react-i18next' ;
function MyComponent ( ) {
const { t } = useTranslation ( ) ;
return < div > { t ( "my-key" , "My default value" ) } < / div>
}Proporcionar el valor de inglés predeterminado en el código hace posible usarlo como valor alternativo cuando las cadenas aún no están traducidas y extraer las cadenas del código fuente al archivo YAML de traducción.
Cuando usamos plurales, debemos proporcionar valores predeterminados para zero , one y other valores, según lo solicite nuestro sistema de traducción. Esto se puede hacer pasando los valores predeterminados en las opciones de la función t .
t ( "my-key" , {
"defaultValue.zero" : "{{count}} items" ,
"defaultValue.one" : "{{count}} item" ,
"defaultValue.other" : "{{count}} items" ,
count : ...
} ) El script bin/extract-strings.mjs se puede utilizar para extraer cadenas de traducción del código fuente y colocarlas en el archivo YAML que recoge nuestro sistema de traducción interno. El uso del script está documentado en el propio script.
El script envuelve la herramienta i18next-parser y convierte su salida al formato YAML utilizado internamente. Es posible utilizar un enfoque similar en un tema personalizado, ya sea utilizando la salida estándar i18next-parser como fuente para las traducciones o implementando un transformador personalizado.
Utilice bin/update-modules-translations.mjs para descargar las traducciones más recientes de todos los módulos. Luego, el proceso de compilación agrupa todos los archivos en un único archivo [MODULE]-translations-bundle.js .
La primera vez que se agregan traducciones a un módulo, debe agregar una asignación entre la carpeta del módulo y el nombre del paquete en los sistemas de traducción a la variable MODULE en el script. Por ejemplo, si un módulo está ubicado en src/modules/my-module y el nombre del paquete es cph-theme-my-module , debe agregar:
const MODULES = {
... ,
"my-module" : "cph-theme-my-module"
}Usamos un script de nodo personalizado que ejecuta Lighthouse para realizar pruebas de accesibilidad automatizadas.
Hay dos formas de ejecutar el script:
zcli themes:preview para ejecutarse;Dependiendo del alcance de las pruebas, es posible que se necesiten algunas pruebas manuales además de las anteriores. Herramientas como ax DevTools, lectores de pantalla, por ejemplo VoiceOver, comprobadores de contraste, etc., pueden ayudar en dichas pruebas.
Para ejecutar las auditorías de accesibilidad mientras cambia el tema:
$ yarn install
$ yarn start Cree un archivo .a11yrc.json en la carpeta raíz (ver ejemplo);
zcli activousername y password con las credenciales de un usuario administrador;urls probar (si se deja vacío, el script probará todas las URL);En una consola separada, ejecute las auditorías de accesibilidad en modo de desarrollo:
yarn test-a11y -d Las auditorías A11y se ejecutarán en la vista previa iniciada en el paso 1 .
Para ejecutar auditorías de accesibilidad en el tema en vivo de una cuenta específica, se debe:
yarn installend_user_email , end_user_password , subdomain y urls como variables de entorno y ejecute las auditorías de accesibilidad en modo CI, es decir: 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 Si hay un problema de accesibilidad conocido que debe ignorarse o no puede solucionarse de inmediato, se puede agregar una nueva entrada a la lista de ignorados en el objeto de configuración del script. Esto convertirá el problema de accesibilidad en una advertencia en lugar de un error.
La entrada debe incluir:
path como una cadena de patrón de URL;selector como una cadena.Por ejemplo:
custom: {
ignore: {
tabindex: [
{
path : "*" ,
selector : "body > a.skip-navigation" ,
} ,
] ,
aria - allowed - attr : [
{
path : "/hc/:locale/profiles/:id" ,
selector : "body > div.profile-info"
}
]
} ,
} , En este ejemplo, los errores del tabindex de auditoría con el body > a.skip-navigation se informarán como advertencias en todas las páginas ( * ). Lo mismo sucederá para la auditoría aria-allowed-attr con el body > div.profile-info , pero solo para la página de perfil de usuario /hc/:locale/profiles/:id .
Tenga en cuenta que esto sólo debe utilizarse cuando sea estrictamente necesario. La accesibilidad debe ser un foco y una prioridad al realizar cambios en el tema.
Las solicitudes de extracción son bienvenidas en GitHub en https://github.com/zendesk/copenhagen_theme. Mencione @zendesk/vikings al crear una solicitud de extracción.
Utilizamos confirmaciones convencionales para mejorar la legibilidad del historial del proyecto y automatizar el proceso de lanzamiento. Por lo tanto, el mensaje de confirmación debe respetar el siguiente formato:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
es decir:
chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors
Usamos husky y commitlint para validar mensajes al confirmar.
Usamos acciones de Github junto con semantic-release para lanzar una nueva versión del tema una vez que se fusiona un PR. En cada fusión, semantic-release analiza los mensajes de confirmación e infiere un aumento de la versión semántica. Luego crea una etiqueta git, actualiza la versión del manifiesto y genera el registro de cambios correspondiente.
La siguiente lista describe los tipos de confirmación admitidos y su efecto en la versión y el registro de cambios.
| Tipo | Descripción | Liberar | Registro de cambios |
|---|---|---|---|
| construir | Cambios que afectan el sistema de compilación o las dependencias externas. | - | - |
| faena | Otros cambios que no modifican el código fuente | - | - |
| ci | Cambios en nuestros archivos y scripts de configuración de CI | - | - |
| documentos | Solo cambios en la documentación | - | - |
| logro | Una nueva característica | menor | Características |
| arreglar | Una corrección de errores | parche | Corrección de errores |
| rendimiento | Un cambio de código que mejora el rendimiento | parche | Mejoras de rendimiento |
| refactorizar | Un cambio de código que no corrige un error ni agrega una característica | - | - |
| revertir | Revierte una confirmación anterior | parche | Revierte |
| estilo | Cambios que no afectan el significado del código (espacios en blanco, formato, falta de punto y coma, etc.) | - | - |
| prueba | Agregar pruebas faltantes o corregir pruebas existentes | - | - |
Las confirmaciones que agregan un cambio importante deben incluir BREAKING CHANGE en el cuerpo o pie de página del mensaje de confirmación.
es decir:
feat: update theme to use theming api v2
BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2
Esto luego generará una versión importante y agregará una sección de BREAKING CHANGES en el registro de cambios.
Los informes de errores deben enviarse a través de los canales de soporte estándar de Zendesk: https://www.zendesk.com/contact/
