Dynamische Einstellungen

Der K3 erlaubt die Definition von Einstellungen (wie Texte, Zahlen, Vektoren, Bilder etc.) für eine Erweiterung. Diese können dann je Konfigurator gesetzt werden. Das ergibt insbesondere dann Sinn, wenn eine Erweiterung von mehreren Kunden oder in verschiedenen Kontexten wiederverwendet wird.

Die Einstellung wird durch den Entwickler im Code der Erweiterung registriert und eingebunden und durch den Admin eingepflegt. Der Endkunde bekommt davon nichts mit uns sieht nur das, was der Admin eingepflegt hat. Dass die Einstellung dynamisch ist, weiß der Endkunde nicht.

tip

Merkmale werden vom Endkunden geändert, dynamische Einstellungen vom Admin.

Registrierung

Neue Einstellungen werden mit

const settings: DynamicSetting[] = [
  {
    key: 'additionalPriceDialogText',
    valueType: DynamicSettingValueType.TRANSLATION,
    label:
      'Hier können Sie einen Text festlegen, der unter der Preisübersicht erscheint.',
    defaultValue: '',
  },
  {
    key: 'lightPosition',
    valueType: DynamicSettingValueType.ARRAY,
    label: 'Legen sie die Position der Lampe fest',
    defaultValue: [0, 0, 0],
    isValid: vectorValidator(3),
  },
  {
    key: 'isNightmodeUnlocked',
    valueType: DynamicSettingValueType.BOOLEAN,
    label: 'Soll der Nutzer in den Nachtmodus wechseln könnnen?',
    defaultValue: false,
  },
  {
    key: 'screwDiameter',
    valueType: DynamicSettingValueType.NUMBER,
    label: 'Wie dick sollen die Schrauben (in mm) sein?',
    defaultValue: 8,
  },
];

<K3Main extensions={extensions} additionalDynamicSettings={settings} />

gesetzt. Die Parameter einer Einstellung sind im Typ DynamicSetting dokumentiert. Es gibt:

• key: Entweder Teil des DynamicSettingsKeys enum oder ein beliebiger string.
• valueType: DynamicSettingValueType enum: String (unübersetzt), Number, Translation, Boolean, Image oder Array (braucht einen validator)
• label: String. Wird im Admin Panel beim enstprechenden Feld angezeigt. Wenn es das nicht gibt wird bei Translations der default Value genutzt, sonst der key
• isValid: Validator. Funktion die den Value übergeben bekommt und [boolean (isValid?), string (error message)] zurück gibt. Für ein numerisches Array gibt es die vectorValidator HOF. Für einen Vektor der Länge 5 würde man isValid: vectorValidator(5) nutzen. Standardmäßig wird für arrays ein einfacher validator verwendet, der ein , separated array erwartet.
• parser: Nur für DynamicSettingValueType.ARRAY relevant. Funktion die den Value als string übergeben bekommt und daraus ein JS Array macht. Gibt es keine Angabe, wird ein Standard Parser, der für die meisten Anwendungsfälle ausreichend sein sollte, verwendet.
• defaultValue: Standard-Wert, wenn keiner über settings gesetzt wird. Gibt es keine Angabe, wird undefined verwendet.

Setzen

Das Feld zur Eingabe von Einstellungen kann mit

<EditDynamicSettings
    keys={[
      DynamicSettingsKeys.NAVBAR_BACK,
      DynamicSettingsKeys.NAVBAR_NEXT,
    ]}
/>

eingebunden werden. Statt keys können auch inline neue settings definiert werden (siehe oben). Die Einstellungen können entweder in der Sidebar angezeigt werden oder über display="dialog" in einem Dialog.

Wenn eine andere Komponente zum Starten der Einstellungen genutzt werden soll, kann man DynamicSettingsLaunch verwenden, und als component eine beliebige Komponente mit einer onClick prop verwenden.

Programatisch können settings mit den useSetSetting(s) hooks gesetzt werden.

Lesen

Übersetzungen werden am besten mit dem useDynamicTranslation hook abgerufen. Etwa so:

const translate = useDynamicTranslation();
// mit additionalPriceDialogText könnte der Admin einen Text der unter dem Preis-Dialog auftritt pflegen.
return <Typography>
    {translate("additionalPriceDialogText")}
</Typography>

Arrays werden am besten mit dem useDynamicSettingArray hook abgerufen. Etwa so:

const getArray = useDynamicSettingArray();
// Mit light position könnte der Admin eine Lampe in der 3D Szene positionieren
const lightPosition = getArray<number[]>("lightPosition");

Normale Settings mit useDynamicSetting so:

const getSetting = useDynamicSetting();

// isNightmodeUnlocked würde beispielsweise, wenn durch den Admin auf true gesetzt, dem Konfigurator ein Button zum Wechsel in einen Nachtmodus hinzufügen
const isNightmodeUnlocked = getSetting<boolean>("isNightmodeUnlocked");

// screw diameter könnte vom Admin eingestellt werden. Je nach Einstellung könnten im 3D Modell die Schrauben unterschiedlich dick sein.
const screwDiameter = getSetting<number>("screwDiameter");

Beispiel

Ein Code-Complete Beispiel zu dynamischen Einstellungen findet ihr hier.