copenhagen_theme Télécharger - copenhagen_theme Téléchargement du code source

copenhague_theme

Autre code source

v4.2.3

Télécharger

Thème Copenhague par Zendesk

Le thème Copenhague est le thème Zendesk Guide par défaut. Il est conçu pour être réactif et accessible. Apprenez-en davantage sur la personnalisation de Zendesk Guide ici.

Le thème de Copenhague pour le centre d'aide comprend :

Fichier manifeste
Ensemble de modèles
Feuille de style et fichiers JavaScript
Dossier Actifs.

Comment utiliser

Il s'agit de la dernière version du thème Copenhague disponible pour Guide. Il est possible d'utiliser ce référentiel comme point de départ pour créer votre propre thème personnalisé. Vous pouvez créer ce référentiel comme bon vous semble. Vous pouvez utiliser votre IDE préféré pour développer des thèmes et prévisualiser vos modifications localement dans un navigateur Web à l'aide de ZCLI. Pour plus de détails, lisez la documentation des thèmes zcli.

Personnaliser votre thème

Une fois que vous avez créé ce référentiel, vous pouvez vous sentir libre de modifier les modèles, CSS, JavaScript et de gérer les actifs.

Fichier manifeste

Le manifeste vous permet de définir un groupe de paramètres pour votre thème qui peuvent ensuite être modifiés via l'interface utilisateur de Theming Center. Vous pouvez en savoir plus sur le fichier manifeste ici.

Dossier Paramètres

Si vous avez une variable de type file , vous devez fournir un fichier par défaut pour cette variable dans le dossier /settings . Ce fichier sera utilisé par défaut dans le panneau des paramètres et les utilisateurs peuvent télécharger un fichier différent s'ils le souhaitent. Ex. Si vous souhaitez avoir une variable pour l'image d'arrière-plan d'une section, la variable dans votre fichier manifeste ressemblerait à ceci :

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

Et cela rechercherait un fichier dans le dossier de paramètres nommé : background_image

Ajout d'éléments

Vous pouvez ajouter des actifs au dossier d'actifs et les utiliser dans vos CSS, JavaScript et modèles. Vous pouvez en savoir plus sur les actifs ici

Publier votre thème

Après avoir personnalisé votre thème, vous pouvez télécharger le référentiel sous forme de fichier zip et l'importer dans Theming Center.

Vous pouvez suivre la documentation pour l'importation ici.

Vous pouvez également importer directement depuis GitHub – en savoir plus ici.

Modèles

Le thème comprend tous les modèles utilisés pour un centre d'aide doté de toutes les fonctionnalités disponibles. Liste des modèles dans le thème :

Page d'articles
Page de catégorie
Page de liste des publications de la communauté
Page de publication de la communauté
Page de liste des sujets de la communauté
Page de sujet de la communauté
Page des contributions
En-tête du document
Page d'erreur
Pied de page
En-tête
Page d'accueil
Nouvelle page de publication de la communauté
Nouvelle page de demande
Page des demandes
Page de résultats de recherche
Page de rubrique
Page des abonnements
Page de profil utilisateur

Vous pouvez ajouter jusqu'à 10 modèles facultatifs pour :

Page d'articles
Page de catégorie
Page de rubrique

Pour ce faire, créez des fichiers dans les dossiers templates/article_pages , templates/category_pages ou templates/section_pages . Apprenez-en davantage ici.

Feuille de style et JavaScript

Nous utilisons Rollup pour compiler les fichiers JS et CSS utilisés dans theme- style.css et script.js . Ne les modifiez pas directement car ils seront régénérés lors de la publication.

Pour commencer :

$ yarn install
$ yarn start

Cela compilera tout le code source dans src et styles et surveillera les changements. Il lancera également preview .

Remarques :

Nous n'utilisons pas intentionnellement babel lors de la compilation script.js afin de pouvoir obtenir une sortie de bundle propre. Assurez-vous de n'utiliser que les fonctionnalités ecmascript largement prises en charge (ES2015).
Ne modifiez pas directement style.css , script.js et les fichiers contenus dans le dossier assets . Ils sont régénérés lors de la libération.
L'aperçu nécessite une connexion, alors assurez-vous d'exécuter d'abord yarn zcli login -i si vous ne l'avez pas déjà fait.

Actifs

Le thème Copenhague est livré avec quelques ressources JavaScript, mais vous pouvez ajouter d'autres ressources à votre thème en les plaçant dans le dossier assets .

Composants de réaction

À partir de la version 4.0.0, le thème Copenhague utilise certains composants React pour restituer certaines parties de l'interface utilisateur. Ces composants se trouvent dans le dossier src/modules et sont construits à l’aide de la bibliothèque de composants Zendesk Garden.

Ces composants sont regroupés en tant que modules JavaScript natifs dans le cadre du processus de création du Rollup et sont émis sous forme de fichiers JS dans le dossier assets . Étant donné que les actifs sont renommés lorsqu'un thème est installé, les modules doivent être importés à l'aide de l'assistant d'actifs.

Pour faciliter le processus d'importation des modules, nous avons ajouté un plugin Rollup qui génère une carte d'importation qui mappe le nom du module à l'URL de l'actif. Cette carte d'importation est ensuite injectée dans le modèle document_head.hbs lors de la construction.

Par exemple, si vous avez défini un module nommé my-module dans le dossier src/modules/my-module , vous pouvez l'ajouter au fichier rollup.config.mjs comme ceci :

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

Rollup générera un fichier nommé my-module-bundle.js dans le dossier assets et cette carte d'importation sera ajoutée au modèle document_head.hbs :

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

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

Vous pouvez ensuite importer le module dans vos modèles comme ceci :

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

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

  // ...
script >

Internationalisation

I18n est implémenté dans les composants React à l'aide de la bibliothèque React-i18next. Nous utilisons un fichier JSON plat et nous utilisons . comme séparateur pour les pluriels, ce qui est différent du _ par défaut et il est configuré lors de l'initialisation.

Nous avons également ajouté quelques outils pour pouvoir intégrer la bibliothèque au système de traduction interne utilisé chez Zendesk. Si vous créez un thème personnalisé et que vous souhaitez fournir vos propres traductions, vous pouvez vous référer à la documentation de la bibliothèque pour configurer le chargement de vos traductions.

Intégration avec le système de traduction Zendesk

Ajout de chaînes de traduction

Les chaînes de traduction sont ajoutées directement dans le code source, généralement à l'aide du hook useTranslation , en transmettant la clé et la valeur anglaise par défaut :

}">

 import { useTranslation } from 'react-i18next' ;

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

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

Fournir la valeur anglaise par défaut dans le code permet de l'utiliser comme valeur de secours lorsque les chaînes ne sont pas encore traduites et d'extraire les chaînes du code source vers le fichier YAML de traduction.

Pluriels

Lorsque nous utilisons des pluriels, nous devons fournir des valeurs par défaut pour les valeurs zero , one et other , comme le demande notre système de traduction. Cela peut être fait en passant les valeurs par défaut dans les options de la fonction t .

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

Extraction de chaînes

Le script bin/extract-strings.mjs peut être utilisé pour extraire les chaînes de traduction du code source et les placer dans le fichier YAML récupéré par notre système de traduction interne. L'utilisation du script est documentée dans le script lui-même.

Le script encapsule l'outil i18next-parser et convertit sa sortie au format YAML utilisé en interne. Il est possible d'utiliser une approche similaire dans un thème personnalisé, soit en utilisant la sortie standard i18next-parser comme source pour les traductions, soit en implémentant un transformateur personnalisé.

Mise à jour des fichiers de traduction

Utilisez bin/update-modules-translations.mjs pour télécharger les dernières traductions de tous les modules. Tous les fichiers sont ensuite regroupés par le processus de construction dans un seul fichier [MODULE]-translations-bundle.js .

La première fois que des traductions sont ajoutées à un module, vous devez ajouter un mappage entre le dossier du module et le nom du package sur les systèmes de traduction vers la variable MODULE dans le script. Par exemple, si un module se trouve dans src/modules/my-module et que le nom du package est cph-theme-my-module , vous devez ajouter :

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

Tests d'accessibilité

Nous utilisons un script de nœud personnalisé qui exécute Lighthouse pour les tests d'accessibilité automatisés.

Il existe deux manières d'exécuter le script :

Mode développement - il exécute les audits d'accessibilité sur l'aperçu du thème local, sur un compte spécifique. Il nécessite que zcli themes:preview soit en cours d'exécution ;
Mode CI - il exécute les audits d'accessibilité sur le thème en direct d'un compte spécifique.

En fonction de l'étendue des tests, certains tests manuels peuvent être nécessaires en plus de ceux ci-dessus. Des outils tels que ax DevTools, des lecteurs d'écran, par exemple VoiceOver, des vérificateurs de contraste, etc. peuvent faciliter ces tests.

Mode développement

Pour réaliser les audits d'accessibilité en changeant de thème :

Commencez à compiler et à prévisualiser les modifications comme vous le feriez normalement :

$ yarn install
$ yarn start

Créez un fichier .a11yrc.json dans le dossier racine (voir exemple) ;
1. Spécifiez le compte/sous-domaine pour prévisualiser le thème en vous assurant qu'il correspond au profil zcli actif
2. Remplissez username et password avec les informations d'identification d'un utilisateur administrateur ;
3. Spécifiez les urls à tester (si laissé vide, le script testera toutes les URL) ;
Dans une console distincte, exécutez les audits d'accessibilité en mode développement :

 yarn test-a11y -d

Les audits A11y seront ensuite exécutés sur l'aperçu démarré à l'étape 1 .

Mode CI

Pour réaliser les audits d'accessibilité sur le thème live d'un compte spécifique, il faut :

Installez les modules de nœud :

 yarn install

Définissez end_user_email , end_user_password , subdomain et urls comme variables d'environnement et exécutez les audits d'accessibilité en mode CI, c'est-à-dire :

.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 

Ignorer la liste

S'il existe un problème d'accessibilité connu qui doit être ignoré ou ne peut pas être résolu immédiatement, on peut ajouter une nouvelle entrée à la liste des ignorés dans l'objet de configuration du script. Cela transformera le problème d'accessibilité en un avertissement au lieu d'une erreur.

L'entrée doit inclure :

l'identifiant de l'audit ;
un path sous forme de chaîne de modèle d'URL ;
un selector sous forme de chaîne.

Par exemple:

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"
        }
      ]
    } ,
  } ,

Dans cet exemple, les erreurs pour le tabindex d'audit avec le body > a.skip-navigation seront signalées sous forme d'avertissements dans toutes les pages ( * ). La même chose se produira pour l'audit aria-allowed-attr avec le body > div.profile-info , mais uniquement pour la page de profil utilisateur /hc/:locale/profiles/:id .

Veuillez garder à l’esprit que cela ne doit être utilisé qu’en cas de stricte nécessité. L'accessibilité doit être un objectif et une priorité lors de la modification du thème.

Contribuer

Les demandes de tirage sont les bienvenues sur GitHub à l'adresse https://github.com/zendesk/copenhagen_theme. Veuillez mentionner @zendesk/vikings lors de la création d'une pull request.

Nous utilisons des commits conventionnels pour améliorer la lisibilité de l’historique du projet et automatiser le processus de publication. Le message de commit doit donc respecter le format suivant :

 [optional scope]: 

[optional body]

[optional footer(s)]

type : décrit la catégorie du changement. Voir les types pris en charge.
scope : (facultatif) décrit ce qui est affecté par le changement
sujet : une petite description du changement
body : (facultatif) informations contextuelles supplémentaires sur le changement
pied de page : (facultatif) ajoute des liens externes, des références de problèmes et d'autres méta-informations

c'est à dire :

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

Nous utilisons husky et commitlint pour valider les messages lors de la validation.

Nous utilisons les actions Github avec semantic-release pour publier une nouvelle version du thème une fois qu'un PR est fusionné. À chaque fusion, semantic-release analyse les messages de validation et déduit un changement de version sémantique. Il crée ensuite une balise git, met à jour la version du manifeste et génère le journal des modifications correspondant.

Types de validation

La liste ci-dessous décrit les types de validation pris en charge et leur effet dans la version et le journal des modifications.

Taper	Description	Libérer	Journal des modifications
construire	Modifications qui affectent le système de build ou les dépendances externes	-	-
corvée	Autres changements qui ne modifient pas le code source	-	-
ci	Modifications apportées à nos fichiers de configuration et scripts CI	-	-
documents	Modifications uniquement dans la documentation	-	-
exploit	Une nouvelle fonctionnalité	mineure	Caractéristiques
réparer	Une correction de bug	correctif	Corrections de bugs
performance	Un changement de code qui améliore les performances	correctif	Améliorations des performances
refactoriser	Un changement de code qui ne corrige pas de bug ni n'ajoute de fonctionnalité	-	-
revenir	Annule un commit précédent	correctif	Rétablit
style	Modifications qui n'affectent pas la signification du code (espaces, formatage, points-virgules manquants, etc.)	-	-
test	Ajouter des tests manquants ou corriger des tests existants	-	-

Modifications radicales

Les validations qui ajoutent une modification avec rupture doivent inclure BREAKING CHANGE dans le corps ou le pied de page du message de validation.