Creating and Using Widgets Add-On

A widgets add-on provides custom UI components to reuse them in different applications.

The following conditions must be met:

  • The JAR file contains DemoaddonWidgets.gwt.xml.

  • The JAR manifest must specify the path to *.gwt.xml:

    jar {
        // pack client Java sources
        with copySpec {
            from sourceSets.main.allJava
            include "com/company/demoaddon/**"
            duplicatesStrategy = DuplicatesStrategy.WARN
        }
        // register exported widgetset
        manifest {
            attributes(['Vaadin-Widgetsets': 'com.company.demoaddon.DemoaddonWidgets',
                        'Vaadin-Stylesheets': 'VAADIN/addons/demoaddon/demoaddon.scss'])
        }
    }

The widgetset will be generated automatically based on all JARs with the Vaadin-Widgetsets key in the Manifest. It allows you to use Vaadin add-ons conveniently.

You don’t need to compile widgets in add-ons.

Creating the Widgets Add-on Using Studio

Follow the steps below to create a widgets add-on using Jmix Studio:

  1. Create a new project. Select a UI Widgets Add-On template. Enter the name of the project, for example, "demoaddon". It will be a simple Java project that has the following structure:

    widgets add on prj structure

    JMIX studio supplies an example of a widgets add-on based on the ColorButton GWT component. You can create your own component instead of a ColorButton.

  2. Open the demoaddon.scss file and define your theme style modifications.

  3. Build and publish the add-on to the local maven repository using the following command:

    ./gradlew clean publishToMavenLocal

Using the Widgets Add-on

  1. Open the project you want to apply the widgets add-on.

  2. Create a custom theme, for example, with the helium-extended name.

  3. Open the build.gradle file and make the following changes:

    • Add mavenLocal() to repositories.

    • Remove implementation 'io.jmix.ui:jmix-ui-widgets-compiled' dependency.

    • Include the add-on dependency to the project’s implementation and widgets configurations, for example:

      implementation 'com.company:demoaddon:0.0.1-SNAPSHOT'
      widgets 'com.company:demoaddon:0.0.1-SNAPSHOT'
      implementation 'io.jmix.ui:jmix-ui-widgets'
      widgets 'io.jmix.ui:jmix-ui-widgets'
    • Add the compileWidgets task (change paths according to your application base package):

      compileWidgets {
          generate "com.company.sample.widget.CustomWidgetSet"
          includePaths('**/io/jmix/**/widget/**', '**/com/company/sample/widget/**')
      }
  4. Add the jmix.ui.widget-set property to your application.properties file (adjust location according to the compileWidgets task above):

    jmix.ui.widget-set=com.company.sample.widget.CustomWidgetSet
  5. Reload the project.

  6. Let’s create a new color-button-screen to demonstrate how the component works.

    Open the ColorButtonScreen.java screen controller and add the code that puts the component to the screen:

    ColorButtonScreen.java
    @UiController("sample_ColorButtonScreen")
    @UiDescriptor("color-button-screen.xml")
    public class ColorButtonScreen extends Screen {
        @Subscribe
        protected void onInit(InitEvent event) {
            ColorButton button = new ColorButton(); (1)
            button.setCaption("Button");
            button.setColor("#AFEEEE");
            getWindow().unwrap(Layout.class).addComponent(button); (2)
        }
    }
    1 Initializes a color button component instance.
    2 Retrieves a link to the Vaadin container using the unwrap() method and adds the new component to it.
  7. Start the application and see the result:

    color button