5.8.9. Using Application Components

As mentioned in the Application Components section, any CUBA application can be used as a component of another application. An application component is a full-stack library providing functionality on all layers - from database schema to business logic and UI.

In this section, we’ll consider an example of creating an application component and using it in a project. The component will provide a "Customer Management" functionality and include the Customer entity and corresponding UI screens. The application will use the Customer entity from the component as a reference in its Order entity.

app components sample
Creating the Customer Management component
  1. Create a new project in Studio and specify the following properties on the New project screen:

    • Project name - customers

    • Project namespace - cust

    • Root package - com.company.customers

  2. Edit Project properties and on the Advanced tab, set the Module prefix to cust. This is necessary to assemble component artifacts with names different from the default app.

  3. Create the Customer entity with at least the name attribute. Switch to the Instance name tab and specify add name to the name pattern attributes.

    Warning

    If your component contains @MappedSuperclass persistent classes, make sure they have descendants which are entities (i.e. annotated with @Entity) in the same project. Otherwise such base classes will not be properly enhanced and you will not be able to use them in applications.

  4. Generate DB scripts and create standard screens for the Customer entity: cust$Customer.browse and cust$Customer.edit. After that, go to main menu designer and rename the application menu item to customerManagement.

  5. Click to the App component descriptor link on the Project properties panel. Save the generated descriptor by clicking OK.

  6. Test the Customer Management functionality: Run > Create database, Run > Start application server, then open http://localhost:8080/cust in your web browser.

  7. Install the application component into the local Maven repository by executing the Run > Install app component menu command.

    Tip

    Using the Install app component command is necessary on Windows to avoid file locking issues. On Linux or Mac OS, you can also use the install Gradle task directly.

Creating the Sales application
  1. Create a new project in Studio and specify the following properties on the New project screen:

    • Project name - sales

    • Project namespace - sales

    • Root package - com.company.sales

  2. Edit Project properties and on the App components panel click the plus button next to Custom components. In the Custom application component dialog, select the customers project in the Registered project drop-down list. The list contains all project registered in Studio that have an app-component.xml descriptor. Click OK in the dialog. The Maven coordinates of the Customer Management component will appear in the list of custom components. Save the project properties by clicking OK.

  3. Create the Order entity and add the date and amount attributes. Then add the customer attribute as a many-to-one association with the Customer entity - it should be available in the Type drop-down list.

  4. Generate DB scripts and create standard screens for the Order entity. When creating standard screens, create a order-with-customer-view view that includes the customer attribute and use it for the screens.

  5. Test the application functionality: Run > Create database, Run > Start application server, then open http://localhost:8080/app in your web browser. The application will contain two top level menu items: Customer Management and Application with the corresponding functionality.

Modifying the Customer Management component

Suppose we have to change the component functionality (add an attribute to Customer) and then reassemble the application to incorporate the changes.

  1. Open the customers project in Studio.

  2. Edit the Customer entity and add the address attribute. When saving the entity, select both browser and editor screens to include the new attribute.

  3. Generate DB scripts - a script for altering table will be created. Save the scripts.

  4. Test the changes in the component: Run > Update database, Run > Start application server, then open http://localhost:8080/cust in your web browser.

  5. Re-install the application component into the local Maven repository by executing the Run > Install app component menu command.

  6. Close the customers project and open sales.

  7. Execute Build > Clean, then Build > Assemble project menu commands.

  8. Execute Run > Update database - the update script from the Customer Management component will be executed.

  9. Execute Run > Start application server and open http://localhost:8080/app in your web browser - the application will contain the Customer entity and screens with the new address attribute.

Sharing the Customer Management component

You can share the application component by uploading it to a remote Maven repository.

  1. Stop the Studio server.

  2. Set up a repository and make it a proxy for the public CUBA repository https://repo.cuba-platform.com/content/groups/work.

  3. Open build.gradle of the customers project in a text editor. Replace the repository and its credentials in buildscript/repositories section and add the uploadRepository to the cuba section:

    buildscript {
        ...
        repositories {
            maven {
                url 'http://repo.company.com/nexus/content/groups/work' // repository containing CUBA and your own artifacts
                credentials {
                    username(rootProject.hasProperty('repoUser') ? rootProject['repoUser'] : 'admin')
                    password(rootProject.hasProperty('repoPass') ? rootProject['repoPass'] : 'admin123')
                }
            }
    ...
    cuba {
        ...
        uploadRepository {
            url = 'http://repo.company.com/nexus/content/repositories/snapshots' // repository for uploading your artifacts
            user = 'admin'
            password = 'admin123'
        }
    }
  4. Open the command line and run gradle assemble in the customers project root directory. This ensures your new repository caches CUBA artifacts required for working in Studio.

  5. In the Studio server window, specify your repository and credentials instead of the standard CUBA repository. Start the Studio server.

  6. Open the customers project in Studio.

  7. In the Studio Search dialog (Alt-/), find the uploadArchives Gradle task and run it. You can also run this task from the command line. The Customer Management component artifacts will be uploaded to your repository.

  8. Remove the component artifacts from your local Maven repository to ensure that they will be downloaded from the remote repository when the sales application is assembled the next time: just delete the .m2/repository/com/company folder located in your user home directory.

  9. Open the customers project in Studio. The repository URL in its build.gradle will be automatically changed to the one specified in the Studio server window.

  10. Now you can assemble and run the application - the Customer Management component will be downloaded from the remote repository.