Download de copenhagen_theme - download do código-fonte de copenhagen

copenhague_theme

Outro código-fonte

v4.2.3

Baixar

Tema Copenhague da Zendesk

O tema Copenhagen é o tema padrão do Zendesk Guide. Ele foi projetado para ser responsivo e acessível. Saiba mais sobre como personalizar o Zendesk Guide aqui.

O tema Copenhague para a Central de Ajuda consiste em:

Arquivo de manifesto
Conjunto de modelos
Folha de estilo e arquivos JavaScript
Pasta de ativos.

Como usar

Esta é a versão mais recente do tema Copenhague disponível para o Guide. É possível usar este repositório como ponto de partida para construir seu próprio tema customizado. Você pode bifurcar este repositório como achar melhor. Você pode usar seu IDE favorito para desenvolver temas e visualizar suas alterações localmente em um navegador da web usando ZCLI. Para obter detalhes, leia a documentação dos temas zcli.

Personalizando seu tema

Depois de bifurcar este repositório, você poderá editar modelos, CSS, JavaScript e gerenciar ativos.

Arquivo de manifesto

O manifesto permite que você defina um grupo de configurações para o seu tema que pode então ser alterado por meio da IU no Theming Center. Você pode ler mais sobre o arquivo de manifesto aqui.

Pasta de configurações

Se você tiver uma variável do tipo file , precisará fornecer um arquivo padrão para essa variável na pasta /settings . Este arquivo será usado no painel de configurações por padrão e os usuários poderão fazer upload de um arquivo diferente, se desejarem. Ex. Se você quiser ter uma variável para a imagem de fundo de uma seção, a variável em seu arquivo de manifesto seria mais ou menos assim:

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

E isso procuraria um arquivo dentro da pasta de configurações chamado: background_image

Adicionando ativos

Você pode adicionar ativos à pasta de ativos e usá-los em CSS, JavaScript e modelos. Você pode ler mais sobre ativos aqui

Publicando seu tema

Depois de personalizar seu tema, você pode baixar o repositório como um arquivo zip e importá-lo para o Theming Center.

Você pode acompanhar a documentação para importação aqui.

Você também pode importar diretamente do GitHub – saiba mais aqui.

Modelos

O tema inclui todos os modelos usados para uma Central de Ajuda que possui todos os recursos disponíveis. Lista de modelos no tema:

Página do artigo
Página de categoria
Página da lista de postagens da comunidade
Página de postagem da comunidade
Página da lista de tópicos da comunidade
Página de tópico da comunidade
Página de contribuições
Cabeçalho do documento
Página de erro
Rodapé
Cabeçalho
Página inicial
Nova página de postagem da comunidade
Nova página de solicitação
Página de solicitações
Página de resultados de pesquisa
Página da seção
Página de assinaturas
Página de perfil do usuário

Você pode adicionar até 10 modelos opcionais para:

Página do artigo
Página de categoria
Página da seção

Você faz isso criando arquivos nas pastas templates/article_pages , templates/category_pages ou templates/section_pages . Saiba mais aqui.

Folha de estilo e JavaScript

Usamos Rollup para compilar os arquivos JS e CSS que são usados no tema - style.css e script.js . Não edite-os diretamente, pois eles serão regenerados durante o lançamento.

Para começar:

$ yarn install
$ yarn start

Isso irá compilar todo o código-fonte em src e styles e observar as alterações. Ele também iniciará preview .

Notas:

Intencionalmente não usamos babel ao compilar script.js para que possamos obter uma saída de pacote limpa. Certifique-se de usar apenas recursos ecmascript amplamente suportados (ES2015).
Não edite style.css , script.js e os arquivos dentro da pasta assets diretamente. Eles são regenerados durante a liberação.
A visualização requer login, portanto, execute primeiro yarn zcli login -i se ainda não tiver feito isso.

Ativos

O tema Copenhagen vem com alguns ativos JavaScript, mas você pode adicionar outros ativos ao seu tema colocando-os na pasta de assets .

Componentes de reação

A partir da versão 4.0.0, o tema Copenhagen usa alguns componentes React para renderizar partes da UI. Esses componentes estão localizados na pasta src/modules e são criados usando a biblioteca de componentes do Zendesk Garden.

Esses componentes são agrupados como módulos JavaScript nativos como parte do processo de criação do Rollup e são emitidos como arquivos JS na pasta de assets . Como os ativos são renomeados quando um tema é instalado, os módulos precisam ser importados usando o auxiliar de ativos.

Para facilitar o processo de importação dos módulos, adicionamos um plugin Rollup que gera um mapa de importação que mapeia o nome do módulo para a URL do ativo. Este mapa de importação é então injetado no modelo document_head.hbs durante a construção.

Por exemplo, se você definiu um módulo chamado my-module na pasta src/modules/my-module , poderá adicioná-lo ao arquivo rollup.config.mjs assim:

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

O rollup irá gerar um arquivo chamado my-module-bundle.js na pasta assets e este mapa de importação será adicionado ao modelo document_head.hbs :

{ "imports": { "my-module": "{{asset 'my-module-bundle.js'}}", } } ">

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

Você pode então importar o módulo em seus modelos assim:

import { something } from "my-module"; // ... ">

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

  // ...
script >

Internacionalização

I18n é implementado nos componentes React usando a biblioteca react-i18next. Usamos um arquivo JSON simples e usamos . como separador de plurais, que é diferente do padrão _ e é configurado durante a inicialização.

Também adicionamos algumas ferramentas para poder integrar a biblioteca ao sistema interno de tradução utilizado no Zendesk. Se você estiver construindo um tema personalizado e quiser fornecer suas próprias traduções, você pode consultar a documentação da biblioteca para configurar o carregamento de suas traduções.

Integração com o sistema de tradução Zendesk

Adicionando strings de tradução

Strings de tradução são adicionadas diretamente no código-fonte, geralmente usando o gancho useTranslation , passando a chave e o valor padrão em inglês:

}">

 import { useTranslation } from 'react-i18next' ;

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

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

Fornecer o valor padrão em inglês no código torna possível usá-lo como um valor substituto quando as strings ainda não foram traduzidas e extrair as strings do código-fonte para o arquivo YAML de traduções.

Plurais

Ao usar plurais, precisamos fornecer valores padrão para zero , one e other valores, conforme solicitado pelo nosso sistema de tradução. Isso pode ser feito passando os valores padrão nas opções da função t .

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

Extração de string

O script bin/extract-strings.mjs pode ser usado para extrair strings de tradução do código-fonte e colocá-las no arquivo YAML que é obtido por nosso sistema interno de tradução. O uso do script está documentado no próprio script.

O script envolve a ferramenta i18next-parser e converte sua saída para o formato YAML usado internamente. É possível usar uma abordagem semelhante em um tema personalizado, usando a saída padrão i18next-parser como fonte para traduções ou implementando um transformador personalizado.

Atualizando arquivos de tradução

Use bin/update-modules-translations.mjs para baixar as traduções mais recentes para todos os módulos. Todos os arquivos são então agrupados pelo processo de construção em um único arquivo [MODULE]-translations-bundle.js .

Na primeira vez que as traduções são adicionadas a um módulo, você precisa adicionar um mapeamento entre a pasta do módulo e o nome do pacote nos sistemas de tradução para a variável MODULE no script. Por exemplo, se um módulo estiver localizado em src/modules/my-module e o nome do pacote for cph-theme-my-module , você precisará adicionar:

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

Teste de acessibilidade

Usamos um script de nó personalizado que executa o lighthouse para testes automatizados de acessibilidade.

Existem duas maneiras de executar o script:

Modo de desenvolvimento - executa as auditorias de acessibilidade na visualização do tema local, em uma conta específica. Requer que zcli themes:preview esteja em execução;
Modo CI - executa auditorias de acessibilidade no tema ativo de uma conta específica.

Dependendo do escopo do teste, alguns testes manuais podem ser necessários além dos acima. Ferramentas como axe DevTools, leitores de tela, por exemplo, VoiceOver, verificadores de contraste, etc., podem auxiliar nesses testes.

Modo de desenvolvimento

Para executar auditorias de acessibilidade ao alterar o tema:

Comece a compilar e visualizar as alterações como faria normalmente:

$ yarn install
$ yarn start

Crie um arquivo .a11yrc.json na pasta raiz (ver exemplo);
1. Especifique a conta/subdomínio para visualizar o tema, certificando-se de que corresponde ao perfil zcli ativo
2. Preencha username e password com as credenciais de um usuário administrador;
3. Especifique quais urls testar (se deixado em branco, o script testará todos os URLs);
Em um console separado, execute as auditorias de acessibilidade no modo de desenvolvimento:

 yarn test-a11y -d

As auditorias A11y serão então executadas na visualização iniciada na etapa 1 .

Modo CI

Para realizar auditorias de acessibilidade no tema ativo de uma conta específica, é necessário:

Instale módulos de nó:

 yarn install

Defina end_user_email , end_user_password , subdomain e urls como variáveis de ambiente e execute as auditorias de acessibilidade no modo CI, ou seja:

.zendesk.com/hc/en-us/
    https://.zendesk.com/hc/en-us/requests/new
    https://.zendesk.com/hc/en-us/requests" 
yarn test-a11y"> end_user_email= 
end_user_password= 
subdomain= 
urls="
    https://.zendesk.com/hc/en-us/
    https://.zendesk.com/hc/en-us/requests/new
    https://.zendesk.com/hc/en-us/requests" 
yarn test-a11y 

Lista de ignorados

Se houver um problema de acessibilidade conhecido que deva ser ignorado ou que não possa ser corrigido imediatamente, pode-se adicionar uma nova entrada à lista de ignorados no objeto de configuração do script. Isso transformará o problema de acessibilidade em um aviso em vez de um erro.

A entrada deve incluir:

o ID da auditoria;
um path como uma string de padrão de URL;
um selector como uma string.

Por exemplo:

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

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

Neste exemplo, erros para o tabindex de auditoria com o seletor body > a.skip-navigation serão relatados como avisos em todas as páginas ( * ). O mesmo acontecerá para a auditoria aria-allowed-attr com o seletor body > div.profile-info , mas apenas para a página de perfil do usuário /hc/:locale/profiles/:id .

Lembre-se de que isso só deve ser usado quando for estritamente necessário. A acessibilidade deve ser um foco e uma prioridade ao fazer alterações no tema.

Contribuindo

Solicitações pull são bem-vindas no GitHub em https://github.com/zendesk/copenhagen_theme. Mencione @zendesk/vikings ao criar uma solicitação pull.

Usamos commits convencionais para melhorar a legibilidade do histórico do projeto e automatizar o processo de lançamento. A mensagem de commit deve, portanto, respeitar o seguinte formato:

 [optional scope]: 

[optional body]

[optional footer(s)]

tipo: descreve a categoria da mudança. Consulte os tipos suportados.
escopo: (opcional) descreve o que é afetado pela mudança
assunto: uma pequena descrição da mudança
corpo: (opcional) informações contextuais adicionais sobre a mudança
rodapé: (opcional) adiciona links externos, referências de problemas e outras metainformações

ou seja:

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

Usamos husky e commitlint para validar mensagens durante o commit.

Usamos ações do Github junto com semantic-release para lançar uma nova versão do tema assim que um PR for mesclado. Em cada mesclagem, semantic-release analisa as mensagens de commit e infere um aumento de versão semântica. Em seguida, ele cria uma tag git, atualiza a versão do manifesto e gera o changelog correspondente.

Tipos de confirmação

A lista abaixo descreve os tipos de commit suportados e seus efeitos no lançamento e no changelog.

Tipo	Descrição	Liberar	Registro de alterações
construir	Mudanças que afetam o sistema de compilação ou dependências externas	-	-
tarefa	Outras mudanças que não modificam o código-fonte	-	-
ci	Mudanças em nossos arquivos e scripts de configuração de CI	-	-
documentos	Apenas a documentação muda	-	-
façanha	Um novo recurso	menor	Características
consertar	Uma correção de bug	correção	Correções de bugs
desempenho	Uma mudança de código que melhora o desempenho	correção	Melhorias de desempenho
refatorar	Uma alteração de código que não corrige um bug nem adiciona um recurso	-	-
reverter	Reverte um commit anterior	correção	Reverte
estilo	Mudanças que não afetam o significado do código (espaço em branco, formatação, falta de ponto e vírgula, etc.)	-	-
teste	Adicionar testes ausentes ou corrigir testes existentes	-	-

Quebrando mudanças

Os commits que adicionam uma alteração significativa devem incluir BREAKING CHANGE no corpo ou rodapé da mensagem de commit.