copenhagen_theme
v4.2.3
Das Kopenhagen-Design ist das Standardthema von Zendesk Guide. Es ist so konzipiert, dass es reaktionsschnell und zugänglich ist. Erfahren Sie hier mehr über die Anpassung von Zendesk Guide.
Das Kopenhagen-Thema für das Help Center besteht aus:
Dies ist die neueste Version des Kopenhagen-Themes, die für Guide verfügbar ist. Es ist möglich, dieses Repository als Ausgangspunkt für die Erstellung Ihres eigenen benutzerdefinierten Themes zu verwenden. Sie können dieses Repository nach Belieben teilen. Sie können Ihre bevorzugte IDE zum Entwickeln von Designs verwenden und Ihre Änderungen mithilfe von ZCLI lokal in einem Webbrowser in der Vorschau anzeigen. Weitere Informationen finden Sie in der Dokumentation zu zcli-Themen.
Sobald Sie dieses Repository geforkt haben, können Sie Vorlagen, CSS, JavaScript bearbeiten und Assets verwalten.
Mit dem Manifest können Sie eine Gruppe von Einstellungen für Ihr Theme definieren, die dann über die Benutzeroberfläche im Theming Center geändert werden können. Weitere Informationen zur Manifestdatei finden Sie hier.
Wenn Sie eine Variable vom Typ file haben, müssen Sie im Ordner /settings eine Standarddatei für diese Variable bereitstellen. Diese Datei wird standardmäßig im Einstellungsfeld verwendet und Benutzer können bei Bedarf eine andere Datei hochladen. Ex. Wenn Sie eine Variable für das Hintergrundbild eines Abschnitts haben möchten, würde die Variable in Ihrer Manifestdatei etwa so aussehen:
{
...
"settings" : [ {
"label" : "Images" ,
"variables" : [ {
"identifier" : "background_image" ,
"type" : "file" ,
"description" : "Background image for X section" ,
"label" : "Background image" ,
} ]
} ]
} Und dies würde nach einer Datei im Einstellungsordner mit dem Namen background_image suchen
Sie können dem Asset-Ordner Assets hinzufügen und diese in Ihrem CSS, JavaScript und Ihren Vorlagen verwenden. Mehr zum Thema Vermögenswerte können Sie hier lesen
Nachdem Sie Ihr Theme angepasst haben, können Sie das Repository als zip Datei herunterladen und in das Theming Center importieren.
Sie können der Dokumentation zum Importieren hier folgen.
Sie können auch direkt von GitHub importieren – erfahren Sie hier mehr.
Das Design umfasst alle Vorlagen, die für ein Help Center verwendet werden, das über alle verfügbaren Funktionen verfügt. Liste der Vorlagen im Theme:
Sie können bis zu 10 optionale Vorlagen hinzufügen für:
Dies erreichen Sie, indem Sie Dateien in den Ordnern templates/article_pages , templates/category_pages oder templates/section_pages erstellen. Erfahren Sie hier mehr.
Wir verwenden Rollup, um die JS- und CSS-Dateien zu kompilieren, die im Theme verwendet werden – style.css und script.js . Bearbeiten Sie diese nicht direkt, da sie während der Veröffentlichung neu generiert werden.
Um zu beginnen:
$ yarn install
$ yarn start Dadurch wird der gesamte Quellcode in src und styles kompiliert und auf Änderungen überwacht. Es wird auch preview gestartet.
Hinweise:
script.js damit wir eine saubere Bundle-Ausgabe erhalten. Stellen Sie sicher, dass Sie nur allgemein unterstützte Ecmascript-Funktionen (ES2015) verwenden.style.css , script.js und die Dateien im assets -Ordner nicht direkt. Sie werden bei der Freisetzung regeneriert.yarn zcli login -i ausführen, falls Sie dies noch nicht getan haben. Das Kopenhagen-Design enthält einige JavaScript-Assets. Sie können Ihrem Design jedoch auch andere Assets hinzufügen, indem Sie diese im assets -Ordner ablegen.
Ab Version 4.0.0 verwendet das Copenhagen-Theme einige React-Komponenten, um Teile der Benutzeroberfläche zu rendern. Diese Komponenten befinden sich im Ordner src/modules und werden mithilfe der Zendesk Garden-Komponentenbibliothek erstellt.
Diese Komponenten werden im Rahmen des Rollup-Build-Prozesses als native JavaScript-Module gebündelt und als JS-Dateien im assets -Ordner ausgegeben. Da Assets bei der Installation eines Themes umbenannt werden, müssen die Module mit dem Asset-Helper importiert werden.
Um den Import der Module zu vereinfachen, haben wir ein Rollup-Plugin hinzugefügt, das eine Importzuordnung generiert, die den Modulnamen der Asset-URL zuordnet. Diese Importzuordnung wird dann während des Builds in die Vorlage document_head.hbs eingefügt.
Wenn Sie beispielsweise ein Modul mit dem Namen my-module im Ordner src/modules/my-module definiert haben, können Sie es wie folgt zur Datei rollup.config.mjs hinzufügen:
export default defineConfig ( [
// ...
// Configuration for bundling modules in the src/modules directory
{
// ...
input : {
"my-module" : "src/modules/my-module/index.js" ,
} ,
// ...
}
] ) ; Rollup generiert eine Datei mit dem Namen my-module-bundle.js im assets -Ordner und diese Importzuordnung wird der Vorlage document_head.hbs hinzugefügt:
< script type =" importmap " >
{
"imports" : {
"my-module" : "{{asset 'my-module-bundle.js'}}" ,
}
}
script >Anschließend können Sie das Modul wie folgt in Ihre Vorlagen importieren:
I18n wird in den React-Komponenten mithilfe der React-i18next-Bibliothek implementiert. Wir verwenden eine flache JSON-Datei und verwenden . als Trennzeichen für Pluralformen, das sich vom Standard _ unterscheidet und bei der Initialisierung konfiguriert wird.
Wir haben auch einige Tools hinzugefügt, um die Bibliothek in das bei Zendesk verwendete interne Übersetzungssystem integrieren zu können. Wenn Sie ein benutzerdefiniertes Design erstellen und Ihre eigenen Übersetzungen bereitstellen möchten, können Sie in der Bibliotheksdokumentation nachlesen, wie Sie das Laden Ihrer Übersetzungen einrichten.
Übersetzungszeichenfolgen werden direkt im Quellcode hinzugefügt, normalerweise mithilfe des useTranslation Hooks, wobei der Schlüssel und der englische Standardwert übergeben werden:
import { useTranslation } from 'react-i18next' ;
function MyComponent ( ) {
const { t } = useTranslation ( ) ;
return < div > { t ( "my-key" , "My default value" ) } < / div>
}Durch die Bereitstellung des englischen Standardwerts im Code ist es möglich, ihn als Ersatzwert zu verwenden, wenn Zeichenfolgen noch nicht übersetzt sind, und die Zeichenfolgen aus dem Quellcode in die YAML-Übersetzungsdatei zu extrahieren.
Bei der Verwendung von Pluralformen müssen wir Standardwerte für die zero , one und other Werte angeben, wie von unserem Übersetzungssystem verlangt. Dies kann durch die Übergabe der Standardwerte in den Optionen der t -Funktion erfolgen.
t ( "my-key" , {
"defaultValue.zero" : "{{count}} items" ,
"defaultValue.one" : "{{count}} item" ,
"defaultValue.other" : "{{count}} items" ,
count : ...
} ) Mit dem Skript bin/extract-strings.mjs können Übersetzungszeichenfolgen aus dem Quellcode extrahiert und in die YAML-Datei eingefügt werden, die von unserem internen Übersetzungssystem übernommen wird. Die Verwendung des Skripts ist im Skript selbst dokumentiert.
Das Skript umschließt das i18next-parser -Tool und konvertiert seine Ausgabe in das intern verwendete YAML-Format. Es ist möglich, einen ähnlichen Ansatz in einem benutzerdefinierten Theme zu verwenden, indem man entweder die Standardausgabe i18next-parser als Quelle für Übersetzungen verwendet oder einen benutzerdefinierten Transformator implementiert.
Verwenden Sie bin/update-modules-translations.mjs um die neuesten Übersetzungen für alle Module herunterzuladen. Alle Dateien werden dann durch den Build-Prozess in einer einzigen [MODULE]-translations-bundle.js Datei gebündelt.
Wenn einem Modul zum ersten Mal Übersetzungen hinzugefügt werden, müssen Sie der MODULE Variable im Skript eine Zuordnung zwischen dem Modulordner und dem Paketnamen auf den Übersetzungssystemen hinzufügen. Wenn sich ein Modul beispielsweise in src/modules/my-module befindet und der Paketname cph-theme-my-module lautet, müssen Sie Folgendes hinzufügen:
const MODULES = {
... ,
"my-module" : "cph-theme-my-module"
}Wir verwenden ein benutzerdefiniertes Knotenskript, das Lighthouse für automatisierte Barrierefreiheitstests ausführt.
Es gibt zwei Möglichkeiten, das Skript auszuführen:
zcli themes:preview ;Abhängig vom Testumfang können zusätzlich zu den oben genannten Tests einige manuelle Tests erforderlich sein. Tools wie ax DevTools, Bildschirmleseprogramme wie VoiceOver, Kontrastprüfer usw. können solche Tests unterstützen.
So führen Sie die Barrierefreiheitsprüfungen durch, während Sie das Design ändern:
$ yarn install
$ yarn start Erstellen Sie eine .a11yrc.json Datei im Stammordner (siehe Beispiel);
zcli Profil übereinstimmtusername und password mit den Anmeldeinformationen eines Admin-Benutzers aus.urls getestet werden sollen (wenn leer gelassen wird, testet das Skript alle URLs);Führen Sie in einer separaten Konsole die Barrierefreiheitsprüfungen im Entwicklungsmodus aus:
yarn test-a11y -d A11y-Audits werden dann mit der in Schritt 1 gestarteten Vorschau ausgeführt.
Um die Barrierefreiheitsprüfungen für das Live-Theme eines bestimmten Kontos durchzuführen, muss man:
yarn installend_user_email , end_user_password , subdomain und urls als Umgebungsvariablen fest und führen Sie die Barrierefreiheitsprüfungen im CI-Modus durch, d. h.: 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
Wenn ein bekanntes Barrierefreiheitsproblem vorliegt, das ignoriert werden sollte oder nicht sofort behoben werden kann, kann man der Ignorierliste im Konfigurationsobjekt des Skripts einen neuen Eintrag hinzufügen. Dadurch wird das Barrierefreiheitsproblem in eine Warnung statt in eine Fehlermeldung umgewandelt.
Der Eintrag sollte Folgendes enthalten:
path als URL-Musterzeichenfolge;selector als String.Zum Beispiel:
custom: {
ignore: {
tabindex: [
{
path : "*" ,
selector : "body > a.skip-navigation" ,
} ,
] ,
aria - allowed - attr : [
{
path : "/hc/:locale/profiles/:id" ,
selector : "body > div.profile-info"
}
]
} ,
} , In diesem Beispiel werden Fehler für den Audit- tabindex mit dem body > a.skip-navigation als Warnungen auf allen Seiten gemeldet ( * ). Dasselbe geschieht für das Audit aria-allowed-attr mit dem body > div.profile-info , jedoch nur für die Benutzerprofilseite /hc/:locale/profiles/:id .
Bitte beachten Sie, dass dies nur dann verwendet werden sollte, wenn dies unbedingt erforderlich ist. Bei Änderungen am Theme sollte die Barrierefreiheit im Mittelpunkt und an erster Stelle stehen.
Pull-Requests sind auf GitHub unter https://github.com/zendesk/copenhagen_theme willkommen. Bitte erwähnen Sie @zendesk/vikings, wenn Sie eine Pull-Anfrage erstellen.
Wir nutzen herkömmliche Commits, um die Lesbarkeit des Projektverlaufs zu verbessern und den Release-Prozess zu automatisieren. Die Commit-Nachricht sollte daher das folgende Format einhalten:
[optional scope]:
[optional body]
[optional footer(s)]
dh:
chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors
Wir verwenden husky und commitlint um Nachrichten beim Commit zu validieren.
Wir verwenden Github-Aktionen zusammen mit semantic-release , um eine neue Version des Themas zu veröffentlichen, sobald ein PR zusammengeführt wird. Bei jeder Zusammenführung analysiert semantic-release die Commit-Nachrichten und leitet daraus einen semantischen Versionssprung ab. Anschließend wird ein Git-Tag erstellt, die Manifestversion aktualisiert und das entsprechende Änderungsprotokoll generiert.
Die folgende Liste beschreibt die unterstützten Commit-Typen und ihre Auswirkungen im Release und Changelog.
| Typ | Beschreibung | Freigeben | Änderungsprotokoll |
|---|---|---|---|
| bauen | Änderungen, die sich auf das Buildsystem oder externe Abhängigkeiten auswirken | - | - |
| lästige Pflicht | Andere Änderungen, die den Quellcode nicht verändern | - | - |
| ci | Änderungen an unseren CI-Konfigurationsdateien und Skripten | - | - |
| Dokumente | Lediglich die Dokumentation ändert sich | - | - |
| feat | Eine neue Funktion | unerheblich | Merkmale |
| Fix | Eine Fehlerbehebung | Patch | Fehlerbehebungen |
| perf | Eine Codeänderung, die die Leistung verbessert | Patch | Leistungsverbesserungen |
| Refaktor | Eine Codeänderung, die weder einen Fehler behebt noch eine Funktion hinzufügt | - | - |
| zurücksetzen | Setzt einen vorherigen Commit zurück | Patch | Kehrt zurück |
| Stil | Änderungen, die sich nicht auf die Bedeutung des Codes auswirken (Leerzeichen, Formatierung, fehlende Semikolons usw.) | - | - |
| prüfen | Fehlende Tests hinzufügen oder vorhandene Tests korrigieren | - | - |
Commits, die eine bahnbrechende Änderung hinzufügen, sollten BREAKING CHANGE im Text oder in der Fußzeile der Commit-Nachricht enthalten.
dh:
feat: update theme to use theming api v2
BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2
Dadurch wird dann eine Hauptversion generiert und im Änderungsprotokoll ein Abschnitt BREAKING CHANGES hinzugefügt.
Fehlerberichte müssen über die Standard-Supportkanäle von Zendesk eingereicht werden: https://www.zendesk.com/contact/
