Theme Pack Configuration

Theming in our Blazor Library offers a powerful and isolated approach, allowing each component to have a different set of CSS classes depending on the selected theme. For example, in Theme A, a BlazorButton component may have the "btn" CSS class applied, while in Theme B, it could be the "button" CSS class.

To define a theme in our Blazor Library, two parts are involved: a JSON file and a CSS file. The JSON file, known as the theme pack configuration, plays a crucial role in theme definition. It specifies:

  1. Related CSS files: The theme pack configuration identifies the associated CSS files that contribute to the styling of components within the theme.
  2. Component appearance and variants: It defines the visual appearance and any variants specific to the theme for each component. This allows you to customize the look and feel of components within different themes.

By leveraging the theme pack configuration and CSS files, you have the flexibility to create unique themes and achieve a cohesive visual experience across your application. In the following sections, we will delve deeper into the process of working with theme pack configurations and customizing component appearance to bring your desired themes to life.

Defining Themes and Associated CSS/JS Files

A theme pack in our Blazor Library can consist of multiple themes, each offering unique visual styles. A theme can import its associated CSS/JS file, ensuring that the CSS/JS is loaded only when the theme is selected.

To specify the associated CSS/JS files for a theme, you can use the Imports value in the theme pack configuration. Here's an example:

{
    "Name": "Default Pack",
    "Author": "Blazor Library",
    "Themes":
    [
        {
            "Name": "Default Theme",
            "Imports":
            [
                {
                    "href": "./my-website.min.css",
                    "rel": "stylesheet",
                    "custom-html-attribute": "attribute value"
                },
                {
                    "href": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
                    "rel": "stylesheet",
                    "integrity": "sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM",
                    "crossorigin": "anonymous"
                },
                {
                    "href": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js",
                    "rel": "text/javascript",
                    "integrity": "sha384-geWF76RCwLtnZ8qwWowPQNguL3RmwHVBC9FhGdlKrxdiJJigb/j/68SIy3Te4Bkz",
                    "crossorigin": "anonymous"
                }
            ],
            ...
        }
    }
}

With this configuration, the Blazor Library will generate the following HTML tags:

<link href="./my-website.min.css" rel="stylesheet" custom-html-attribute="attribute value" />
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous" />
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-geWF76RCwLtnZ8qwWowPQNguL3RmwHVBC9FhGdlKrxdiJJigb/j/68SIy3Te4Bkz" crossorigin="anonymous" rel="text/javascript"></script>

By defining the associated CSS/JS files in the theme pack configuration, you can effortlessly import external stylesheets or reference local CSS/JS files specific to each theme. This enables you to incorporate custom styles or leverage popular CSS frameworks to achieve the desired appearance for your themes.

Defining Component Variants in a Theme

In our theme system, you can define the appearances of components by specifying their variants. Variants allow you to customize different aspects of a component, such as colors, sizes, or styles. By defining component variants, you can create diverse visual styles for components within a theme.

To define component variants, modify the value of the Components property in the theme configuration. Here's an example:

{
    "Name": "Default Pack",
    "Author": "Blazor Library",
    "Themes":
    [
        {
            "Name": "Default Theme",
            ...
            "Components":
            {
                "BlazorButton": "btn",
                "BlazorButton.small": "btn-sm",
                "BlazorButton.large": "btn-lg",
                "BlazorButton.primary": "btn-primary",
                "BlazorButton.secondary": "btn-secondary",
                "BlazorButton.success": "btn-success",
                "BlazorButton.danger": "btn-danger",
                "BlazorButton.warning": "btn-warning",
                "BlazorButton.info": "btn-info",
                ...
            }
        }
    }
}

In this example, BlazorButton represents the base CSS class that will be included whenever a variant is selected, while small, large, primary, secondary, and so on, denote the component variants. When a variant is applied, it will combine the base CSS class with the variant CSS class to create the final styling for the component.

To render a component with a specific variant, you can specify the variant using the Variants property. Here are a few examples:

Rendering without any variant:

<BlazorButton type="button">Hello World</BlazorButton>

Output:

<button class="btn" type="button">Hello World</button>

Rendering with a single variant:

<BlazorButton Variants='new[] {"primary"}' type="button">Hello World</BlazorButton>

Output:

<button class="btn btn-primary" type="button">Hello World</button>

Rendering with multiple variants:

<BlazorButton Variants='new[] {"primary","large"}' type="button">Hello World</BlazorButton>

Output:

<button class="btn btn-primary btn-lg" type="button">Hello World</button>

Extending Themes and Custom Components

To modify specific aspects of a theme, such as adding new variants to a component or changing the CSS class of a component variant, you can achieve that by extending a base theme. In the Blazor Library, extending a theme involves creating a new theme pack configuration with the desired changes.

For instance, let's consider the built-in theme of Blazor Library named Default Theme. Here's an example theme pack configuration that extends the Default Theme:

{
    "Name": "My Theme Pack",
    "Author": "Contoso",
    "Themes":
    [
        {
            "Name": "Default Theme",
            ...
            "Components":
            {
                "BlazorButton": "button",
                "BlazorButton.primary": "color-red"
            }
        }
    ]
}

In this example, the first theme defined in the theme pack configuration is named Default Theme serving as the base theme to extend. The Name and Author properties of the theme pack configuration can differ from the base theme and reflect the details of your custom theme pack.

To extend the base theme, specify the desired modifications within the Components section. You can change the CSS class of a component or introduce new variants by mapping the component names to their corresponding CSS classes. For example, BlazorButton is mapped to the button CSS class, and BlazorButton.primary is mapped to the color-red CSS class.

Once you have created the theme pack configuration to extend a theme and define custom components, you need to inform the Blazor Library to fetch the new theme pack configuration in the Program.cs file. This ensures that your extended theme and custom components are properly integrated into your application.

To accomplish this, add the following code snippet to the Program.cs file:

builder.Services.AddBlazorComponents(options => options.ExtendedThemePackPath = "theme-packs/MyThemePack.json");

In this example, ExtendedThemePackPath is set to the path where your extended theme pack configuration file (MyThemePack.json) is located. Adjust the path accordingly based on your project's file structure.

By including this code, you are instructing the Blazor Library to fetch the specified theme pack configuration, enabling seamless integration of your extended theme and custom components into your Blazor application.

Remember to replace "theme-packs/MyThemePack.json" with the actual path and filename of your theme pack configuration file.

By following these steps, you can extend themes, define custom components, and ensure that your application incorporates the desired styles and functionality from the extended theme pack configuration.

An error has occurred. This application may no longer respond until reloaded. Reload 🗙