Zum Hauptinhalt springen

Theming-Implementierung

Jutro verfügt über einen Theming-Mechanismus, der für ein einheitliches Styling in der gesamten Anwendung sorgt. Während der Design-Teil über Design-Token erledigt wird, benötigt die Anwendung CSS-Variablen, um die Stildefinition zu verarbeiten. Diese CSS-Variablen sind das Ergebnis der Umwandlung von Design-Token in CSS-Variablen. Es sind auch einige zusätzliche Anpassungsoptionen verfügbar.

Sie können Design-Token auch mit benutzerdefinierten Komponenten verwenden. Sie müssen entweder neue Design-Token für diese benutzerdefinierten Komponenten definieren oder eine Zuordnungsdatei von vorhandenen Token zu neuen CSS-Variablen zur Umwandlungskonfiguration hinzufügen. Weitere Informationen zur Konfiguration benutzerdefinierter Komponenten finden Sie hier.

Note: Der alte Theming-Mechanismus, der auf der manuellen Definition der --GW- CSS-Variablen-Überschreibungen basierte, wurde verworfen, ist aber immer noch verfügbar und wird für legacy-Komponenten unterstützt. Wechseln Sie zu einer Version der Dokumentation, die älter als 10.0 ist, um mehr Details zu diesem Mechanismus anzuzeigen, oder gehen Sie zur Legacy-Theming-Seite, um herauszufinden, wie Sie zur Verwendung von Design-Token wechseln können.

Funktionsweise des Jutro-Theming​

Die Anpassung des Jutro-Themings wird als Teil der NPM-Pakete @jutro/theme, @jutro/theme-styles und @jutro/design-tokens implementiert. In den meisten Fällen müssen Sie jedoch nicht direkt auf sie verweisen.

Normalerweise erstellen Sie Ihre Anwendung mit der Methode start() aus @jutro/app. Dieser Launcher umfasst Ihre Anwendung mit einer Root-Komponente <ThemeProvider> zur Anwendung der Themes. Wenn Sie der Methode start() keine Konfiguration zur Anpassung des Themings übergeben, wird das Standard-Theme (Enterprise) verwendet.

Das Theming auf der Implementierungsebene basiert auf CSS-Variablen mit globalem Umfang, die allgemeine CSS-Werte für verschiedene Aspekte des Erscheinungsbildes definieren. Einige gelten für einzelne Komponenten, andere für ganze Gruppen von Komponenten. Diese Variablenwerte werden während des Umwandlungsprozesses aus den definierten Design-Token zugeordnet.

Jede der von Jutro bereitgestellten Variablen wird nach einer dieser beiden Konventionen benannt (alles in Großbuchstaben):


# CSS variables generated from design tokens
--JDS-[<CATEGORY>]-[<PROPERTY>]-[<MODIFIER>]

# legacy option still applied in many components
--GW-[<OPTIONAL-COMPONENT-OR-GROUP-NAME>]-<STYLING-ASPECT>-[<OPTIONAL-VARIANT>]

Beispiele:

  • --JDS-COLOR-BACKGROUND-BRAND
  • --JDS-COLOR-BACKGROUND-ERROR-SUBTLE
  • --GW-ACCORDION-BORDER-FOCUS
  • --GW-FOCUS-ERROR-COLOR-DARK
Warning: Keine Guidewire-definierten CSS-Variablen --JDS- verwenden, um benutzerdefinierte Komponenten zu formatieren. CSS-Variablen, die aus Tokens unter dem Namensraum „jds“ generiert werden, sind NICHT Teil der API-Oberfläche und werden NICHT von der NBC-Richtlinie (Non-Breaking Changes) abgedeckt. Das bedeutet, dass alle CSS-Variablen, die mit --JDS- beginnen, ihre Benennung/Werte zwischen den Versionen ändern können, daher raten wir dringend davon ab, sie zur Gestaltung von Anwendungen zu verwenden. Verwenden Sie stattdessen eine der hier genannten Methoden.

Do's und Don'ts des Themings​

Wenn Sie die auf dieser Seite beschriebenen Leitplanken befolgen, ist Ihr Theme einfacher zu pflegen und zu aktualisieren. Nachfolgend finden Sie eine Zusammenfassung der Leitplanken:

  1. Um Jutro-Stile global anzupassen, verwenden Sie Design-Token.
  2. Verwenden Sie nur Teile von Jutro Design System, die zu unserer API-Oberfläche gehören
  3. Ändern Sie keine der generierten CSS-Variablendefinitionen manuell.
  4. Verwenden Sie keine --JDS- CSS-Variablen, um benutzerdefinierte Komponenten zu gestalten, sondern befolgen Sie die empfohlenen Ansätze.
  5. Verlassen Sie sich bei der Definition der Stile nicht auf interne Implementierungsdetails der Komponenten, einschließlich CSS-Variablen und Klassennamen.
  6. Verwenden Sie niemals Brute-Force- oder Hacking-Stile, indem Sie komplexe Selektoren schreiben, um Komponenten auf einer Seite anzupassen. Verwenden Sie zum Beispiel nicht „die erste Schaltfläche im Formular“.

Anpassung der Jutro-Stile und Erhaltung der Aktualisierbarkeit​

Der offiziell unterstützte Weg zur Anpassung von Jutro-Komponenten ist die Verwendung von Design-Token und das Ergebnis ihrer Umwandlung in CSS-Variablen.

Wenn sich infolge einer Komponentenuntersuchung die --JDS--CSS-Variablen ändern, die von einer Komponente verwendet werden, nimmt Guidewire die erforderlichen Änderungen in die Konfiguration des Prozesses der Umwandlung im Design-Token zu CSS-Variablen auf, um die Aktualisierung auf die neuere Version ohne negative Auswirkungen oder manuelles Eingreifen des Verbrauchers zu ermöglichen.

Einrichten eines neuen Themes für Ihre Anwendung​

Die beste Möglichkeit, Stile global zu überschreiben, ist die Erstellung eines benutzerdefinierten Designs. Standardmäßig verwenden Jutro-Anwendungen das Theme „Enterprise“. Um zu einem anderen Theme zu wechseln, gehen Sie wie folgt vor.

  1. Bereiten Sie die Design-Token-Konfiguration für Ihr benutzerdefiniertes Theme vor – der Vorgang wird auf dieser Seite beschrieben
  2. Übergeben Sie das richtige Theme, damit start in ./src/startApp.js funktioniert:
import themesConfig from './.themesConfig.json';

start(Jutro, {
        ...
        themeConfig: themesConfig.sampleTheme,
    });

Weitere Einzelheiten finden Sie auf den Dokumentationsseiten zu Design-Token.

Zugriff auf externe Themes​

Abschließend, nach allen Transformationen, wird Ihre Theme-Definition in der tokenOverrides.css-Datei (oder einer Datei mit einem anderen Namen) gespeichert, die die CSS-Variablenwerte enthält, die aus den Design-Token zugeordnet werden. Da der Link zu dieser Datei aus der Theme-Konfiguration übernommen und als href-Wert in einem HTML-<link>-Tag verwendet wird, können Sie die CSS-Datei auf einem anderen Server ablegen. In diesem Fall müssen Sie in Ihrem .themesConfig.json nicht input-path angeben, da Sie keine Transformationen lokal ausführen. Es reicht aus, den Link zu Ihrer tokenOverrides.css-Datei als Wert von output-file-name hinzuzufügen.

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "output-file-name": "https://example.com/theme/tokenOverrides.css"
    }
  }
}

Damit können Sie die folgenden Szenarien realisieren:

  1. Gemeinsame Nutzung des benutzerdefinierten Themes durch verschiedene Anwendungen.
  2. Bereitstellung von neuen Themes unabhängig von der Anwendung.

Beachten Sie jedoch, dass die Dateien vom Client-Browser aus verfügbar sein müssen und dass das Caching möglicherweise verhindert, dass der Client-Browser aktualisierte Stile sofort anzeigt.

Bitte beachten Sie auch, dass Remote-Dateien während des Upgrades nicht automatisch migriert werden.

Anpassen der Stile einer einzelnen Instanz einer Jutro-Komponente​

Sie können eine className-Eigenschaft verwenden, um das Erscheinungsbild einer einzelnen Instanz einer Jutro-Komponente anzupassen.

  1. Bereiten Sie Ihre eigene CSS-Klasse vor:
.myCustomButtonStyles {
  background: red;
}
  1. Übergeben Sie sie mit Hilfe der className-Eigenschaft an die Komponente:
import { Button } from '@jutro/component';
import styles from './myStyles.module.scss';

const MyForm = () => {
  // this instance of button is going to have use our red background instead of the default one
  return <Button className={styles.myCustomButtonStyles}>Get insured!</Button>;
};

Versuchen Sie nicht, die Standardstile der Jutro-Komponenten zu überschreiben, indem Sie die Namen der von Jutro bereitgestellten CSS-Klassen extrahieren und sie direkt in Ihren Stylesheets überschreiben. Wenn Sie direkt auf eine Jutro-Klasse verweisen, funktionieren Ihre Anpassungen nicht mehr, wenn Jutro zu einem anderen Hashing-Mechanismus wechselt oder die Klasse umbenennt. Klassennamen sind nicht Teil Jutro-API-Oberfläche und ihre Namen können sich von Release zu Release ändern.

.jut__Button__button {
  //this is WRONG, please do not do this
  background: red;
}

Schriftarten, Bilder, statische Dateien​

Alle statischen Ressourcen befinden sich in der Regel in Ihrem src/assets-Ordner. Sie können sie wie folgt referenzieren:

  • aus HTML-Schablonen, z. B. mit dem Platzhalterpräfix %PUBLIC_URL%:

    <img src="%PUBLIC_URL%/<path-to-the-image-under-src-assets>" />

  • aus dem JS-Code (z. B. als Teil des render() der Komponente), mit der Umgebungsvariable PUBLIC_URL:

    render() {
        return (
            <img src={`${process.env.PUBLIC_URL}/<path-to-the-image-under-src-assets>`} />
        );
    }

  • aus CSS-Dateien entweder mit dem absoluten oder relativen Pfad – in diesem Fall sucht der Browser nach den Dateien, die relativ zu der CSS-Datei sind, in welcher der Link angegeben ist

Hinzufügen von benutzerdefinierten Schriftarten​

Um eine benutzerdefinierte Schriftart anzuwenden, legen Sie sie in Ihrem src/assets/fonts-Ordner ab und schließen sie in Ihre SCSS-Datei ein.

@font-face {
  font-family: Acme;
  src: url(./assets/fonts/Acme-Regular.ttf);
}

Sie können die Schriftart auf jede Komponente oder Klasse anwenden. Wenn Sie eine Theme-Schriftart ersetzen möchten, überschreiben Sie das entsprechende Design-Token.

Schriftarten in Webpack 5​

Wenn Sie zu Webpack 5 wechseln, sollte Ihre Theme.scss-Datei nur noch Schriftarten speichern, wie unten gezeigt:

Theme.scss
$fonts-root: '~@jutro/theme/assets/fonts';

// ------------------------------------
//   GROUNDED CSS MODULES
// ------------------------------------
@import '~@jutro/theme/assets/fonts/fonts';

Es wird nicht empfohlen, weitere Informationen zu Ihrer Theme.scss-Datei hinzuzufügen.