2.2. Creating your extension project

Creating your extension project includes 2 mandatory steps:

Create an extension webapp named custom-extension.war which contains resources and configurations. The webapps are loaded in the order defined in the list of dependencies of the PortalContainerDefinition.
Next, tell eXo Platform to load WEB-INF/conf/configuration.xml of your extension by declaring the PortalContainerConfigOwner listener in WEB-INF/web.xml of your extension:
```
<web-app>

    <display-name>custom-extension</display-name>

    <listener>

        <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>

    </listener>

    

</web-app>
```

Create an extension config named custom-extension-config.jar that declares your extension webapp as a dependency of the portal container. This means, under custom-extension-config.jar, you need to create /conf/configuration.xml with the following sample content:


<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"

   xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">

   <external-component-plugins>

      <!-- The full qualified name of the PortalContainerConfig -->

      <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>

      <component-plugin>

         <!-- The name of the plugin -->

         <name>Add PortalContainer Definitions</name>

         <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions -->

         <set-method>registerChangePlugin</set-method>

         <!-- The full qualified name of the PortalContainerDefinitionPlugin -->

         <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>

         <priority>101</priority>

         <init-params>

            <values-param>

               <name>apply.specific</name>

               <value>portal</value>

            </values-param>

            <object-param>

               <name>addDependencies</name>

               <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">

                  <!-- The name of the portal container -->

                  <field name="dependencies">

                     <collection type="java.util.ArrayList">

                        <value>

                           <string>custom-extension</string>

                        </value>

                     </collection>

                  </field>

               </object>

            </object-param>

         </init-params>

      </component-plugin>

   </external-component-plugins>

</configuration>

In which:

The custom-extension webapp is added as a dependency to the portal container named portal.
Your own extension will be loaded by the priority order which is defined in conf/configuration.xml. Thus, you need to pay attention to this priority value to make sure your own extension take effect. Currently, the priority value that defines platform-extension.war is "100". If you want to make your configurations in custom-extension.war override those in platform-extension.war, you should give one priority value which is higher than "100" (for example, "101") in /conf/configuration.xml under your custom-extension-conf.jar.

Note

The loading priority of your extension depends on your specific needs.

Registering your extension manually

For Tomcat:

Add the custom-extension.war file to the $PLATFORM_TOMCAT_HOME/webapps/ directory.
Add the custom-extension-config.jar file to the $PLATFORM_TOMCAT_HOME/lib directory.
Restart the server.

For JBoss:

Create the custom-extension.war!/WEB-INF/jboss-deployment-structure.xml file with the following content that declares platform.ear as a dependency of the custom extension.


<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">

<!-- This is the top level ear module, which contains all the classes in the EAR's lib folder     -->

    <deployment>

        <!-- This allows you to define additional dependencies, it is the same as using the Dependencies: manifest attribute -->

        <dependencies>

            <module name="deployment.platform.ear" export="true"/>

        </dependencies>

    </deployment>

</jboss-deployment-structure>

Add the custom-extension.war file to the $PLATFORM_JBOSS_HOME/standalone/deployments/ directory.
Add the custom-extension-config.jar file to the $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear!/lib directory.
Restart the server.

Registering your extension with script

To avoid manual registration which might cause errors (for example, invalid .xml files) in application.xml, eXo Platform provides the extension.sh script. It allows you to simplify your extension management in both Tomcat and JBoss EAP by copying all jars and wars of your extension in one step and uninstalling them without searching in the lib directory (more than 400 jars) and in the webapps directory (about 60 wars).

eXo Platform currently uses this script to automate the extension installation as described in Installing extensions.

Here are the steps you need to follow:

Create a custom-extension folder in the $PLATFORM_HOME/extensions directory.
Create 2 sub-folders, including lib and webapps in custom-extension.
Copy custom-extension-config.jar, then paste it into the custom-extension/lib sub-folder.
Copy custom-extension.war, then paste it into the custom-extension/webapps sub-folder.
Run the following command to install the custom-extension project:
- Linux/Mac: ./extension.sh --install custom-extension
- Windows: extension.bat --install custom-extension
Restart the server.

Tip

By running the extension.sh --help command, you will know how to use this script.