Plugin development

This part of the reference documentation covers all the technologies and concepts that describes plugin development.

1. Plugins basics

2. Spring based plugins

2.1. Auto-configurations

This mechanism is counterpart of Spring boot auto-configuration. It works on the same principles, but it has some tweaks to avoid conflicts with Spring mechanism and mayhem that would happen when developer unintentionally includes Spring boot auto-configurations to classpath. The main difference for developers using auto-configurations is fact that you need to use @EnablePluginAutoConfiguration. Then magic happens. It is opt-in mechanism, so unless you use @EnablePluginAutoConfiguration on one of your configuration classes, no configuration will be applied and no beans will be created.

You should only ever add one @EnablePluginAutoConfiguration annotation. The best idea is that you add it to your primary @Configuration class only.

2.1.1. Overriding auto-configurations

Auto-configuration is non-invasive. At any point, you can start to define your own configuration to replace specific parts of the auto-configuration. Beans defined by auto-configuration will disable automatically and only your beans will be taken into Spring Context.

2.1.2. Disabling specific auto-configuration classes

It works the same way as in Spring Boot. If you find that specific auto-configuration classes that you do not want are being applied, you can use the exclude attribute of @EnablePluginAutoConfiguration to disable them, as shown in the following example:

@Configuration
@EnablePluginAutoconfiguration(exclude = JakartaServletsAutoconfiguration.class)
public class PluginConfiguration {
    // beans definitions
}

If the class is not on classpath, you can use excludeName attribute of annotation and specify fully qualified name instead. Finally, you can also control the list of auto-configuration classes to exclude by using the rarog.autoconfigure.exclude property.

2.1.3. Creating your own auto-configuration

If you work on libraries for Rarog plugins, you might want to develop you own auto-configuration.

You can referer to Spring boot reference firstly to understand better concept of auto-configurations. Here we will focus on differences between Spring Boot auto-configurations and Rarog auto-configurations and how to add your own auto-configuration.

2.1.4. Differences with Spring Boot

To avoid conflicts with Spring Boot, Rarog auto-configuration must be annotated with @PluginAutoConfiguration. It should be enough in most of the cases, but it comes with some side effects. Adding Rarog auto-configuration to META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file will have no effect. Instead, use META-INF/rarog/eu.rarogsoftware.rarog.platform.plugins.autoconfigure.PluginAutoConfiguration.imports. Notice that not only file name changes, but also we use catalog rarog instead of spring. We did it to keep it consistent with other Rarog mechanisms and configurations and to further draw difference between Spring and Rarog.

In any other aspect Rarog auto-configurations works the same way as Spring Boot auto-configurations. You can use condition annotations.

2.1.5. Creating your own auto-configuration

First step to create your own autoconfiguration is to create configuration class annotated with @Configuration and @PluginAutoConfiguration.

@Configuration
@EnablePluginAutoconfiguration
public class NewAutoConfiguration {
    // beans definitions
}

Then you need to define default beans based on conditions that allow to detect current state of system. Remember to give developers option to override your defaults.

@ConditionalOnBean(ComponentDefinedByUserOrLibrary.class)
@ConditionalOnMissingBean(AutoconfiguredBeanClass.class)
@Bean
AutoconfiguredBeanClass autoconfiguredBeanClass(ComponentDefinedByUserOrLibrary object) {
    // creation of instance
}

You can also use Spring environmental values using @Value or @ConfigurationProperties annotations. It allows to adjust you auto-configuration using properties from environment (like system properties or application.properties defined properties).

When your auto-configuration class is ready, you need add it’s fully qualified name to file META-INF/rarog/eu.rarogsoftware.rarog.platform.plugins.autoconfigure.PluginAutoConfiguration.imports in your library. Remember to add one name per line to make it work.

You can use # to add comments in META-INF/rarog/*.imports files.

At this point you auto-configuration should be automatically picked during spring context initialization, when your library is present in classpath.

2.2. Themes support

2.2.1. Rarog themes

Rarog comes with premade page layouts and colors schemes, but developer can use its own themes if default one is not sufficient or not to liking. Themes are built using Thymeleaf templates.

Each page import template fragments form theme template located under location: theme/<type>.html (example: theme/genericpage.html). So by simply providing templates under these locations, each plugin can provide its own set of theme fragments.

Each theme template should consist of following fragments:

  • headblock - <head> tag of html page to import to final page. It should include all necessary css and js imports.

  • themeHeader - can be any tag, which will be put before page content. Usually it is <header> or <nav> tag for including common navigation/header panel on each page.

  • themeFooter - can be any tag, which will be put after page content. Usually it is <footer> tag for page common footer.

These fragments are necessary for each theme template. Template may consist of more fragments, but they will not be imported by Rarog core pages.

Color scheme

Color scheme is intended to be implemented by theme templates. Rarog pages use Bootstrap for UI components, which comes with build-in support for color modes. So all themes should keep compatiblity this mechanism by defining currrent color scheme using data-bs-theme on html tag.

Default Rarog theme comes with build-in dark mode support.