Adding Style to Oqtane Themes

Oqtane's dynamic nature requires special handling

Oqtane is a powerful platform that lets you create modular apps with Blazor that can run on any device. It does not impose any UI style on you and gives you some basic themes based on Bootstrap. However, if you want to customize your site to match a specific design, you will need to add your own style. In this post, I will show you how to apply style to a theme and to individual modules.

Themes are site-wide

To create a custom theme from scratch, you need to use the theme builder tool. First, run the Oqtane.Server project and follow the setup instructions. Then, open the admin console and select theme management. There, you can click on the Create Theme button and begin designing your theme.

We've created a simple theme that uses Bootstrap as the foundation. For this article, we'll stick with that and modify it a bit.

Resources are the key

Resources in Oqtane are elements that can be used to customize the appearance and functionality of the web pages. They include scripts and stylesheets that are loaded in the HTML document when the page is rendered. There are different levels of resources in Oqtane, depending on where they are defined and how they are applied. The following is a summary of the resource hierarchy and how to reference them in Oqtane.

• ThemeInfo - Inherits from Oqtane.Models.Theme. Styles applied to the installable theme package level and will apply to all defined themes.

• Themes/Theme1.razor - Inherits from ThemeBase and has Resources as well. This will allow you to have multiple themes defined in a single Theme package.

• Containers/Contaner1.razor - Inherits from ContainerBase and ThemeBase. Resources applied here will apply to each module on the page that use that container. When you add a module to a page, you can select the container for the module to reside.

Special Note: Although the Resources list is available at the Container level, CSS resources are not processed at this level. You can only apply JS resources at the container level, not CSS.

When we want to customize the appearance of our theme, we can choose between two methods of applying style. Each method has its own advantages and disadvantages, depending on the situation and the desired outcome. Let's compare and contrast these two options and see how they work.

One way to handle the styling was to define it at the ThemeInfo level and use SCSS to compile all the style for the whole site, including all the controls and event modules. This method works well when the modules and the theme are designed as a single product. The advantage is that the designer can see the style as a whole in one place. The drawback is that the modules lose their modularity and their own individual resources.

A purer approach to applying style is to apply just the style you need, just at the right level. Let’s look at applying style to a particular Theme. We’ll assume that your style guide defines three colors. Primary #004960, Secondary #006686, and Tertiary #6e963e.

To create a theme that can display different background colors for any module on a page, we need to define some styles at the theme level. We will make three containers and a containers.css file that contains the styles for each container. Then, we can add modules to the page and see how they look with different colors.

The following text is a simple demonstration of how to apply CSS styles in Oqtane. Oqtane does not prevent you from using SCSS, which I often use in my projects. I will also write another post about how to style Modules in Oqtane.