5.5.11. Custom Visual Components

This section contains an overview of different ways of creating custom web UI components in CUBA applications. The practical tutorial of using these approaches is located in the Creating Custom Visual Components section.

A new component can be created with the following technologies:

  • On the basis of a Vaadin add-on.

    This is the simplest method. The following steps are required to use an add-on in your application:

    • Add a dependency to the add-on artifact to build.gradle.

    • Create the web-toolkit module in your project. This module contains a GWT widgetset file and allows you to create client-side parts of visual components.

    • Include the add-on widgetset to the widgetset of your project.

    • If the component’s look does not fit the application theme, create a theme extension and define some CSS for the new component.

    See an example in the Using a Third-party Vaadin Component section.

  • As a wrapper of a JavaScript library.

    This method is recommended if you already have a pure JavaScript component that does what you need. To use it in your application, you need to do the following:

    • Create a server-side Vaadin component in the web module. A server component defines an API for server code, access methods, event listeners, etc. The server component must extend the AbstractJavaScriptComponent class. Note that the web-toolkit module with a widgetset is not required when integrating a JavaScript component.

    • Create a JavaScript connector. A connector is a function that initializes the JavaScript component and is responsible for interaction between JavaScript and the server-side code.

    • Create a state class. Its public fields define what data are sent from the server to the client. The class must extend JavaScriptComponentState.

    See an example in the Using a JavaScript library section.

  • As a new GWT component.

    This is the recommended method of creating completely new visual components. The following steps are required to create and use a GWT component in your application:

    • Create the web-toolkit module.

    • Create a client-side GWT widget class.

    • Create a server-side Vaadin component.

    • Create a component state class that defines what data are sent between the client and the server.

    • Create a connector class that links the client code with the server component.

    • Create an RPC interface that defines a server API that is invoked from the client.

    See an example in the Creating a GWT component section.

  • As a new resource from WebJar.

    This method allows you to use various JS libraries packaged into JAR files and deployed on Maven Central. The following steps are required to use a component from a WebJar in your application:

    • Add dependency to the compile method of web module:

      compile 'org.webjars.bower:jrcarousel:1.0.0'

    • Create the web-toolkit module.

    • Create a client-side GWT widget class and implement the native JSNI method for creating the component.

    • Create a server-side component class with @WebJarResource annotation.

      This annotation should be used only with ClientConnector inheritors (which are classes of UI components from the web-toolkit module usually). The value of @WebJarResource annotation should be equal to the following path:

      <resource_name>/<resource_version>/<resource>

      It can have one or more (String array) WebJar resource String definitions:

      @WebJarResource({
        "jquery-ui/1.12.1/jquery-ui.min.js",
        "jquery-fileupload/9.12.1/jquery-fileupload.min.js",
        "jquery-fileupload/9.12.1/jquery-fileupload.min.js"
})
public class CubaFileUpload extends CubaAbstractUploadComponent {
    ...
}

    • Add new component to the screen.

There are three levels of integration of a new component into the platform.

  • On the first level, the new component becomes available as a native Vaadin component. An application developer can use this component in screen controllers directly: create a new instance and add it to an unwrapped container. All methods of creating new components described above give you a component on this level of integration.

  • On the second level, the new component is integrated into CUBA Generic UI. In this case, from an application developer perspective, it looks the same as a standard component from the visual components library. The developer can define the component in a screen XML descriptor or create it through ComponentsFactory in a controller. See an example in the Integrating a Vaadin Component into the Generic UI section.

  • On the third level, the new component is available on the Studio components palette and can be used in the WYSIWYG layout editor. See an example in the Support for Custom Visual Components in CUBA Studio section.