Maven Integration

Most of the projects relying on ActiveUI also use some Java code server-side. In these projects, a Maven build process is thus almost always already in place.

In order to streamline the integration of ActiveUI with this build process, we publish ActiveUI as a jar file to https://support.activeviam.com/share/ActiveUI_stable/.

The jar artifact can be consumed by projects based on the activeui-sandbox (as described in the quick start tutorial) or by projects that only import the ActiveUI library in HTML pages.

Jar Structure #

The jar groupId is com.activeviam.activeui and its artifactId is just activeui. It has the following content:

├── META-INF/resources/activeui/ <!-- for script integration -->
|   ├── fonts/
|   ├── locales/
|   └── app.min.js
└── activeui.tgz <!-- for sandbox integration -->

Script-based Integration #

If your project does not require complex client-side customization and just serving something such as the Dashboard widget would be enough, you can opt for the script-based integration of ActiveUI.

In this situation your project could have the following structure:

├── src/main/
|   ├── java/
|   ├── webapp/activeui/
|   |   └── index.html  
└── pom.xml

To plug ActiveUI into your Maven build, first edit the POM to add the new dependency:

<project>
  <!-- ... -->
  <dependencies>
    <!-- ... -->
    <dependency>
      <groupId>com.activeviam.activeui</groupId>
      <artifactId>activeui</artifactId>
    </dependency>
    <!-- ... -->
  </dependencies>
  <!-- ... -->
</project>

With this change, the ActiveUI jar will end up in the war under WEB-INF/lib/.

The index.html content could then be pretty similar to the one in the script integration page but the path to the ActiveUI library would be ./app.min.js.

Sandbox Integration #

Let’s say that we have a project with the following structure:

├── activeui/ <!-- based on ActiveUI sandbox -->
|   ├── src/
|   └──  package.json
├── server/
|   ├── src/
|   └── pom.xml
└── pom.xml <!-- parent POM -->

By simply running mvn clean install -DskipTests (or mvn clean install to also launch the test suite) we want to:

1. build the ActiveUI sandbox in production mode
2. copy the generated assets in the server war under /activeui.

To achieve this goal, the first thing to do is declaring a new dependency in the parent POM:

<!-- pom.xml -->
<project>
  <!-- ... -->
  <modules>
    <module>activeui</module>
    <module>server</module>
  </modules>
  <!-- ... -->
  <properties>
    <!-- ... -->
    <ActiveUIVersion>{{ActiveUIVersion}}</ActiveUIVersion>
    <!-- ... -->
  </properties>
  <!-- ... -->
  <dependencyManagement>
    <dependencies>
      <!-- ... -->
      <dependency>
        <groupId>com.activeviam.activeui</groupId>
        <artifactId>activeui</artifactId>
        <version>${ActiveUIVersion}</version>
      </dependency>
      <!-- ... -->
    </dependencies>
  </dependencyManagement>
  <!-- ... -->
</project>

In our activeui directory, we will create a new POM file:

<!-- activeui/pom.xml -->
<project>
  <parent>
    <!-- point to your parent POM -->
  </parent>

  <artifactId>project-activeui</artifactId>
  <name>Project ActiveUI</name>

  <build>
    <resources>
      <resource>
        <directory>${basedir}/build</directory>
      </resource>
    </resources>

    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <filesets>
            <fileset>
              <!--
                Deleting the activeui directory to force reinstall.
                It makes it easier to upgrade the ActiveUI version in the parent POM.
              -->
              <directory>${basedir}/node_modules/activeui</directory>
            </fileset>
          </filesets>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.10</version>
        <executions>
          <execution>
            <id>unpack</id>
            <phase>initialize</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>com.activeviam.activeui</groupId>
                  <artifactId>activeui</artifactId>
                  <overWrite>true</overWrite>
                  <!-- Only unpack the .tgz file needed by npm -->
                  <includes>*.tgz</includes>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>exec-maven-plugin</artifactId>
          <version>1.4.0</version>
          <executions>
            <execution>
              <id>npm install</id>
              <phase>initialize</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>install</argument>
                </arguments>
              </configuration>
            </execution>

            <execution>
              <id>npm build</id>
              <phase>generate-resources</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>run</argument>
                  <argument>build</argument>
                </arguments>
              </configuration>
            </execution>

            <execution>
              <id>npm test</id>
              <phase>test</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>run</argument>
                  <argument>test</argument>
                </arguments>
                <!--
                  Don't run the JavaScript test suite
                  when installing with -DskipTests.
                -->
                <skip>${skipTests}</skip>
                <environmentVariables>
                   <!--
                     When CI (continuous integration) is false,
                     Create React App launches the tests in watch mode
                   -->
                  <CI>true</CI>
                </environmentVariables>
              </configuration>
            </execution>
          </executions>
      </plugin>
    </plugins>
  </build>
</project>

The unpack task declared in the maven-dependency-plugin section will partially extract the ActiveUI jar and create the file activeui/target/dependency/activeui.tgz. Thus we need the package.json to point to this new path:

{
  "...": "...",
  "devDependencies": {
    "...": "...",
    "activeui": "file:./target/dependency/activeui.tgz"
  }
}

The last step is to edit the server POM:

<!-- server/pom.xml -->
<project>
  <!-- ... -->
  <dependencies>
    <dependency>
      <groupId><!-- put your project groupId --></groupId>
      <artifactId>project-activeui</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack-activeui</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeArtifactIds>project-activeui</includeArtifactIds>
              <outputDirectory>
                ${project.build.directory}/${project.build.finalName}/activeui
              </outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <!-- ... -->
</project>