expressappframework-403068-app-shell-and-base-infrastructure-blazor-application-appearance.md
You can configure the appearance of an XAF ASP.NET Core Blazor application in several ways. DevExpress Blazor includes built-in classic and fluent themes, and the fluent theme support both light and dark modes. You can also apply external Bootstrap themes or libraries such as Bootswatch. This topic describes options you can use to customize your application.
The DevExpress Blazor component suite includes a set of built-in DevExpress themes that are also available in XAF applications. When you create an XAF application, the Template Kit adds these themes to the application Theme Switcher. The following themes are included by default:
The DevExpress.ExpressApp.Blazor package ships with Generic Light and Generic Dark themes. The stylesheet for the Generic Dark theme (dx.dark.css) is used with the Blazing Dark and Fluent Dark themes. The stylesheet for the Generic Light theme (dx.light.css) is applied to all custom themes and other XAF themes.
For more information about DevExpress Blazor Themes, refer to the following topic: Themes.
The application configuration file (MySolution.Blazor.Server\appsettings.json) includes the ThemeSwitcher section that specifies the switcher’s settings and available themes.
Display the list of available Theme Switcher options
Root level options
DefaultItemName specifies the default theme’s name.ShowSizeModeSwitcher specifies whether the Size Mode switcher is visible.Groups contains a collection of theme groups. Each group must have a caption and a collection of themes.Fluent group options
IsFluent specifies whether the current group contains Fluent theme settings.ShowCustomColorSelector specifies whether the custom color selector is visible.ShowModeSwitcher specifies whether the Light/Dark selector is visible.DefaultMode specifies the default fluent theme mode.Caption specifies the group name in the Theme Switcher.Items contains a collection of themes in the group.CustomUrls contains a collection of custom stylesheets used with the Fluent theme.Fluent item options
Caption specifies the theme’s name in the Theme Switcher.Color specifies the theme’s accent color in the hexadecimal format or a ThemeFluentAccentColor enumeration value.Classic group options
Caption specifies the group name in the Theme Switcher.Items contains a collection of themes in the group.Classic Item options
Caption specifies the theme’s name in the Theme Switcher.
Color specifies square icon color for the Theme Switcher.
Url specifies a link to the theme’s CSS file.
CustomUrls contains a collection of custom stylesheets used with the theme.
"DevExpress": {
"ExpressApp": {
"Languages": "en-US;",
"ShowLanguageSwitcher": false,
"Security": {
// ...
},
"ThemeSwitcher": {
"DefaultItemName": "DevExpress Fluent",
"ShowSizeModeSwitcher": true,
"Groups": [
{
"IsFluent": true,
"ShowModeSwitcher": false,
"ShowCustomColorSelector": false,
"DefaultMode": "Dark",
"Caption": "DevExpress Fluent",
"Items": [
{
"Caption": "Blue",
"Color": "Blue"
},
{
"Caption": "Cool Blue",
"Color": "CoolBlue"
},
{
"Caption": "Desert",
"Color": "Desert"
},
{
"Caption": "Mint",
"Color": "Mint"
},
{
"Caption": "Moss",
"Color": "Moss"
},
{
"Caption": "Orchid",
"Color": "Orchid"
},
{
"Caption": "Purple",
"Color": "Purple"
},
{
"Caption": "Rose",
"Color": "Rose"
},
{
"Caption": "Rust",
"Color": "Rust"
},
{
"Caption": "Steel",
"Color": "Steel"
},
{
"Caption": "Storm",
"Color": "Storm"
}
]
},
{
"Caption": "DevExpress Classic",
"Items": [
{
"Caption": "Blazing Berry",
"Url": "_content/DevExpress.Blazor.Themes/blazing-berry.bs5.min.css",
"Color": "#5c2d91"
},
{
"Caption": "Blazing Dark",
"Url": "_content/DevExpress.Blazor.Themes/blazing-dark.bs5.min.css",
"Color": "#46444a"
},
{
"Caption": "Office White",
"Url": "_content/DevExpress.Blazor.Themes/office-white.bs5.min.css",
"Color": "#fe7109"
},
{
"Caption": "Purple",
"Url": "_content/DevExpress.Blazor.Themes/purple.bs5.min.css",
"Color": "#7989ff"
}
]
}
]
}
}
}
The application gear menu displays the Theme Switcher if your project has more than one theme. To hide the Theme Switcher, specify a single application theme in the appsettings.json file.
"DevExpress": {
"ExpressApp": {
"ThemeSwitcher": {
"Groups": [
{
"Caption": "DevExpress Themes",
"Items": [
{
"Caption": "Office White",
"Url": "_content/DevExpress.Blazor.Themes/office-white.bs5.min.css",
"Color": "#fe7109"
}
]
}
]
}
}
}
If the ThemeSwitcher section does not specify any themes, the application uses the default Fluent Light Blue theme.
You can apply external Bootstrap themes to your XAF ASP.NET Core Blazor application. The following code sample applies the Sketchy theme from the Bootswatch theme set. For more information about Bootswatch themes, refer to the Bootswatch documentation.
"DevExpress": {
"ExpressApp": {
//...
"ThemeSwitcher": {
"DefaultItemName": "DevExpress Fluent",
"ShowSizeModeSwitcher": true,
"Groups": [
{
"Caption": "DevExpress Themes",
"Items": [
// ...
]
},
{
"Caption": "Third Party Themes",
"Items": [
{
"Caption": "Sketchy",
"Url": "https://cdn.jsdelivr.net/npm/[email protected]/dist/sketchy/bootstrap.min.css",
"Color": "#000"
}
]
}
]
}
}
}
The bootstrap-external stylesheet shipped with DevExpress.Blazor.Themes package is added by default. To exclude it, set the ExcludeBootstrapExternal to true:
"DevExpress": {
"ExpressApp": {
//...
"ThemeSwitcher": {
"DefaultItemName": "DevExpress Fluent",
"ShowSizeModeSwitcher": true,
"Groups": [
{
"Caption": "DevExpress Themes",
"Items": [
// ...
]
},
{
"Caption": "Third Party Themes",
"Items": [
{
"Caption": "Custom",
"ExcludeBootstrapExternal": "true";
"Url": "css/custom-bootstrap.min.css",
"Color": "#5c2d91"
}
]
}
]
}
}
}
You can use the IThemeService interface to obtain the current theme, change a theme, and track theme changes.
The following steps describe how to implement an Action that changes your XAF application’s theme to Blazing Dark.
Use the Template Kit to create the new BlazingDarkController.cs Window Controller in the MySolution.Blazor.Server/Controllers folder.
Replace automatically generated file content with the following code:
Run the application. Click the Enable Blazing Dark Action to change the theme. Navigate to the gear menu: the Blazing Dark theme should be selected.
You can add your own stylesheet to a built-in or custom theme. The following code snippet loads custom stylesheets with the Blazing Berry theme:
// ...
{
"Caption": "Blazing Berry",
"Url": "_content/DevExpress.Blazor.Themes/blazing-berry.bs5.min.css",
"Color": "#5c2d91",
// The collection of stylesheets used with the theme.
"CustomUrls": [
// Add a link to the 'dx.light.css' or 'dx.dark.css' stylesheet
// to ensure that XAF renders application components consistently
"_content/DevExpress.ExpressApp.Blazor/dx.light.css",
"css/custom1.css",
"css/custom2.css"
]
},
// ...
XAF can display Blazor applications in different size modes. Users can select from Standard and Compact options in the Theme Switcher.
When you create a new application, the Template Kit enables the Size Mode switcher in the MySolution.Blazor.Server\appsettings.json file. Set the ShowSizeModeSwitcher option to false (or remove the option) to hide the switcher.
// ...
"ThemeSwitcher": {
// "ShowSizeModeSwitcher": true,
// ...
Use the GlobalOptions.SizeMode property to specify the size mode in code. The Compact option corresponds to the Small property value and the Standard option corresponds to the Medium value.
This section demonstrates how CSS classes can help you customize the appearance of various UI elements in XAF ASP.NET Core Blazor applications. You can use CSS to modify items like Actions or layout groups in a Detail View.
Examples in this topic apply customizations to the Employee Detail View from the MainDemo demo project. This project is installed as a part of the XAF package. The default project location is %PUBLIC%\Documents\DevExpress Demos 25.2\Components\XAF\MainDemo.NET.EFCore.
Set the CustomCSSClassName property of an appropriate element (IModelViewLayoutElementBlazor.CustomCSSClassName or IModelActionBlazor.CustomCSSClassName) to a new CSS class name in the Model Editor.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Fin the DOM elements you need to customize and review their CSS classes to build a proper selector.
Use Developer Tools to adjust CSS rules and edit the element according to your needs.
Add these rules with the appropriate selectors to the MySolution.Blazor.Server\wwwroot\css\site.css file.
The following sections describe several popular use cases.
This section explains how to change the font and background colors of the Details group header in the Employee Detail View.
Locate the following layout group in the Model Editor: Employee_DetailView > Layout > Main > SimpleEditors > Person. Set the CustomCSSClassName property to EmployeeInfoGroupStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the dxbl-text and dxbl-group-header classes.
Add the following CSS rules to the site.css file:
Save your changes and refresh the Employee Detail View page to see the result.
This section explains how to customize Property Editors displayed in a Detail View. The example below changes settings for the label and edit box of the First Name Property Editor. This editor is displayed in the Employee Detail View.
Locate the following layout element in the Model Editor: Employee_DetailView > Layout > Main > SimpleEditors > Person > Person_inner > Person_col1 > Person_col1a > FirstName. Set the CustomCSSClassName property to EmployeeFirstNameStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .dxbl-text and .dxbl-text-edit classes.
Add the following CSS rules to the site.css file:
Save your changes and refresh the Employee Detail View page to see the result.
This section explains how to customize Property Editor labels. The example below walks you through the steps needed to add a colon (:) to all editor labels displayed in the Employee Detail View.
Locate the following layout group in the Model Editor: Employee_DetailView > Layout > Main. Set the CustomCSSClassName property to EmployeePropertyEditorCaptionStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .label class.
Add the following CSS rules to the site.css file:
Save your changes and refresh the Employee Detail View page to see the result.
This section explains how to customize the appearance settings of active and inactive tabs in a tabbed layout group. The following example changes the background and caption colors of all tabs displayed in the Employee Detail View.
Locate the following tabbed group in the Model Editor: Employee_DetailView > Layout > Main > Tabs. Set the CustomCSSClassName property to EmployeeTabsStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect element markup to implement an appropriate CSS selector. This example customizes items with the .dxbl-active, .dxbl-text, and .dxbl-tabs-item classes.
Add the following CSS rules to the site.css file:
Save your changes and refresh the Employee Detail View page to see the result.
This section describes two approaches used for Action customization.
The following example changes the background and text colors of the New Action. This customization applies to all Views that display this action.
Locate the following Action node in the Model Editor: Main Demo > ActionDesign > Actions > New. Set the CustomCSSClassName property to NewActionStyle.
Run the application and use the page Inspector tools to locate the newly created class name on the corresponding Detail View page.
Inspect the element’s markup to implement an appropriate CSS selector. This example customizes items with the .NewActionStyle class.
Add the following CSS rules to the site.css file:
Save your changes and refresh the Employee Detail View page to see the result.
The following example changes the New Action’s color settings in the Employee > Details Detail View only.
Add the following CSS rule to the site.css file:
Create a new CustomizeEmployeeDetailViewAction Controller. The created Controller should be a descendant of the Controller class.
Handle the CustomizeControl event to apply the NewActionStyle CSS class to the New Action.
Save your changes and refresh the Employee Detail View page to see the result.
Blazor CSS isolation allows you to you create styles specific to each component, preventing conflicts with other components or libraries. Refer to the following help topic for examples of using CSS isolation with DevExpress components: CSS Isolation.
XAF projects initially do not include component-specific styles, so the bundled stylesheet is not added. To enable isolated styles, uncomment or manually add the wizard-generated stylesheet link in Pages/Host.cshtml.
<!-- Uncomment this link to enable CSS isolation. For more information, refer to the following topic: -->
<!-- https://learn.microsoft.com/en-us/aspnet/core/blazor/components/css-isolation.-->
<link href="_MySolution.Blazor.Server.styles.css" rel="stylesheet">
Note
The MySolution.Blazor.Server.styles.css file is generated when at least one component in the _MySolution.Blazor.Server project contains a CSS file as described in the Microsoft documentation: Enable CSS isolation. Otherwise, the 404 (Not Found) error occurs.