How to package a custom theme to be reusable

Support
#1

Hi, I’d like to package my custom theme (based on halo theme), to be able to reuse it easily across projects.
The custom theme should be used as the base for theme extension in projects, to add only the required custom changes for the app module/project being developed.
I can’t find anything in the docs, but I need it to avoid copy and paste for every project, and build a consistent and versioned theme.

Thanks, Paolo

1 Like
#2

Hi,

It is really important question for us, and it is still not present in docs. We will try to fix it as soon as possible. Until when, I will tell you how to package your custom theme right now.

There are two options to achieve that:

  • use one application component across all your applications that will contain all necessary theme modifications;
  • extract theme as a standalone reusable package.

In order to package your theme as an application component you can use the following steps (these steps are relevant to simple extension of halo theme):

  1. Create project in CUBA Studio
  2. Extend halo theme
  3. Decide, do you want to include halo-ext-defaults.scss file to reusable theme package or not.

If you want to include halo-ext-defaults.scss (variables modifications) then change file app-component.scss in your extended theme:


@import "halo-ext";
@import "halo-ext-defaults"; // add this line to "app-component.scss"

@mixin com_company_mytheme {
  @include com_company_mytheme-halo-ext;
}

After that you can install your app component using Studio menu.

Go to your application project. Remember to extend halo theme in application! Now, if you build application and start it you will see that all changes from app component have been applied.

If you want to create completely new theme see process described here: Creating a Custom Theme - CUBA Platform. Developer’s Manual

This option is useful then you use one of your projects as a base/platform. You can include there all the functionality: model, business logic, styles, etc.

Another option - create Java project from scratch and bundle it as a single JAR file.

As an example of such a custom redistributable theme I’ve prepared halo-facebook theme:

It is a simple Java project that consist of SCSS files and theme properties.

You can build and install it using gradle:


gradle assemble install

After that you can add it to your project as a Maven dependency in two configurations: themes and compile.

Modify your build.gradle file:


configure(webModule) {
    configurations {
        webcontent
    }

    dependencies {
        provided(servletApi)
        compile(guiModule)

        // add these lines
        compile('com.haulmont.theme:halo-facebook:0.1')
        themes('com.haulmont.theme:halo-facebook:0.1')
    }

To inherit this theme and modify it in a project you have to extend this theme. It can be done if you extend “halo” theme and rename themes/halo folder to theme/halo-facebook. Also you have to change styles.scss file:


@import "halo-facebook-defaults";
@import "com.company.demofb/halo-ext-defaults";
@import "app-components";
@import "com.company.demofb/halo-ext";

.halo-facebook {
  // include auto-generated app components SCSS
  @include app_components;

  @include com_company_demofb-halo-ext;
}

The last step is to define halo-facebook-theme.properties file in web-app.properties file:


cuba.themeConfig = havana-theme.properties halo-theme.properties /halo-facebook/halo-facebook-theme.properties

Now, we can build and start our application and choose halo-facebook theme from Help - Settings menu or set default active theme using “cuba.web.theme” application property.

You can find a demo project that uses redistributable halo-facebook theme here: GitHub - cuba-labs/halo-facebook-demo. Remember to build and install halo-facebook from sources before building this project.

#3

Thx Yuriy for the thorough explanation! I haven’t had any chance to try it yet, but I’ll do it ASAP…

P.