App configuration

Common changes⁠link

• See more of Chameleon's messages, or fewer. Set minConsoleLoggingLevel to LoggingLevel.Information while you develop, or to LoggingLevel.None to silence the console. Set minScreenLoggingLevel to show warnings on the components themselves.
• Move toasts and change how long they stay. Set toastAnchor to the corner you want and toastTimeout to the time in milliseconds.
• Choose one language for every user. Set locale to a BCP 47 tag, such as de-CH, to use that language for built-in text and number formats whatever the user's browser language.
• Offer a different on-screen keyboard. Set defaultNumberFieldInputMode to InputMode.Numeric for whole numbers, for example. Each field type has its own setting.

A component's own value always wins over app configuration. A text field with its own inputmode keeps it.

Messages⁠link

Toasts⁠link

A toast that sets its own value keeps it. toastAnimation is the exception: it applies to every toast.

Forms⁠link

Each setting picks the on-screen keyboard a field offers when it sets no inputmode of its own. Every one takes an InputMode: None, Decimal, Email, Numeric, Search, Tel, Text, or Url.

Language⁠link

Performance⁠link

Most apps leave these alone.

Advanced⁠link

Most apps leave these alone.

How settings apply⁠link

• Set a setting to "DEFAULT" to return it to Chameleon's default. locale and repaintOnColorSchemeChange don't take "DEFAULT"; set them to their default value instead.
• Set deferralGap, deferralFlushDelay, and shadowRootVisibility before your first component appears, and redrawGap before the first theme switch, because later changes don't reach the page. Every other setting applies at once, to components already on screen.
• Reading a setting you haven't set gives "DEFAULT", not the value in the Default column.

Call setAppConfiguration() from the package you already import. There's nothing else to set up.

Set it⁠link

Call setAppConfiguration() in your entry point, straight after the package import, and pass only the settings you want to change. The rest keep their current values.

import {
  Corner,
  LoggingLevel,
  setAppConfiguration,
} from "@materia-technologies-inc/chameleon-components-web";

setAppConfiguration({
  minConsoleLoggingLevel: LoggingLevel.Information,
  toastAnchor: Corner.EndEnd,
  toastTimeout: 8000,
});

Call it again whenever a setting needs to change, from a settings panel, for example. Pass "DEFAULT" to return a setting to Chameleon's default.

setAppConfiguration({ toastAnchor: "DEFAULT" });

getAppConfiguration() returns the settings your app has set. Treat the object as read-only and change settings through setAppConfiguration().

import { getAppConfiguration } from "@materia-technologies-inc/chameleon-components-web";

const { toastTimeout, locale } = getAppConfiguration();

Components in your HTML⁠link

Components written into your page's HTML start before your call to setAppConfiguration() runs, so they keep the default shadowRootVisibility. To give them another value, add them from script after the call.

Import setAppConfiguration() from the React package. There's no provider or hook to add.

Set it⁠link

Call setAppConfiguration() in your entry point, before createRoot().render(), so every setting applies from the first render. Pass only the settings you want to change; the rest keep their current values.

import { createRoot } from "react-dom/client";
import {
  DeferralGap,
  InputMode,
  setAppConfiguration,
} from "@materia-technologies-inc/chameleon-components-react";
import { App } from "./App";

setAppConfiguration({
  defaultNumberFieldInputMode: InputMode.Numeric,
  deferralGap: DeferralGap.One,
});

createRoot(document.getElementById("root")!).render(<App />);

Change it while your app runs⁠link

Call setAppConfiguration() from an event handler. Chameleon's components update themselves, so you don't need to hold the setting in React state.

import { CrButton, LoggingLevel, setAppConfiguration } from "@materia-technologies-inc/chameleon-components-react";

export function DiagnosticsButton() {
  return (
    <CrButton onClick={() => setAppConfiguration({ minScreenLoggingLevel: LoggingLevel.Warning })}>
      Show warnings
    </CrButton>
  );
}

Read it⁠link

getAppConfiguration() returns the settings your app has set. It isn't React state, so a component of yours that shows a setting won't re-render when it changes; read it again after you call setAppConfiguration().

import { getAppConfiguration } from "@materia-technologies-inc/chameleon-components-react";

const { locale } = getAppConfiguration();

Set app configuration in Program.cs, where you add Chameleon's services, and change it at run time through IChameleonConfigurationService. Setting names start with a capital, as in ToastTimeout.

Set it⁠link

Assign an AppConfiguration in the options of AddChameleonServices(), with only the properties you want to change.

using Chameleon.Blazor;

builder.Services.AddChameleonServices(options =>
{
    options.AppConfiguration = new AppConfiguration
    {
        MinConsoleLoggingLevel = LoggingLevel.Information,
        ToastAnchor = Corner.EndEnd,
        ToastTimeout = 8000,
    };
});

Assign Default.UseDefault to return a setting to Chameleon's default. DeferralFlushDelay and ToastTimeout are double values in milliseconds.

Change it while your app runs⁠link

Inject IChameleonConfigurationService and assign a new AppConfiguration to its AppConfiguration property. The assignment replaces every setting, and any you leave out return to their defaults. Copy the current configuration with a with expression and change only what you need.

@inject IChameleonConfigurationService ConfigurationService

<CbButton OnClick="ShowWarnings">Show warnings</CbButton>

@code {
    private void ShowWarnings()
    {
        ConfigurationService.AppConfiguration = ConfigurationService.AppConfiguration with
        {
            MinScreenLoggingLevel = LoggingLevel.Warning,
        };
    }
}

The same property returns the settings your app has set: ConfigurationService.AppConfiguration.ToastTimeout.

Settings that need the first render⁠link

Your settings reach the browser once the first Chameleon component renders interactively, never during prerendering. By then it's too late for DeferralGap and DeferralFlushDelay, which keep their defaults, and the components in that first render keep the default ShadowRootVisibility. Every other setting applies as soon as it arrives.